icons

SVGs, Polymer web components and SASS mixins for D2L icons

View larger

Close

[ This description is mirrored from README.md at github.com/BrightspaceUI/icons on 2019-05-22 ]

d2l-icons

d2l-icons contains SVGs, Polymer-based web components and Sass mixins to incorporate D2L iconography into your application.

Installation

d2l-icons can be installed from Bower:

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
tier2	medium level of detail, linear style		24px x 24px	Full set
tier3	medium level of detail, linear style		30px x 30px	Full set
html-editor	for use in the HTML editor		18px x 18px	Full set
emoji	for all your emoji needs, same detail/style as tier1		18px x 18px	Full set

> Browse ALL categories and icons

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 framework, d2l-icons exposes iron-iconset-svg collections for usage with the Polymer 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:

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../iron-icon/iron-icon.html">
<link rel="import" href="../d2l-icons/tier1-icons.html">
<iron-icon icon="d2l-tier1:bookmark-filled"></iron-icon>

You'll need to set the size (ideally 18px, 24px or 30px) and color (ferrite, #494c4e) of the icon. d2l-colors comes in handy:

<link rel="import" href="../d2l-colors/d2l-colors.html">
<style include="d2l-colors">
iron-icon {
    color: var(--d2l-color-ferrite);
    --iron-icon-height: 18px;
    --iron-icon-width: 18px;
}
</style>

If you'd like a different color when the user hovers:

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 and iron-icon directly (see above) works just fine, however we've created a wrapper component called <d2l-icon> which will automatically set the correct icon size, color, and mirror the icon horizontally for right-to-left languages.

<d2l-icon icon="d2l-tier1:gear"></d2l-icon>
<d2l-icon icon="d2l-tier2:gear"></d2l-icon>
<d2l-icon icon="d2l-tier3:gear"></d2l-icon>

It can be used identically to <iron-icon>:

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../d2l-icons/d2l-icon.html">
<link rel="import" href="../d2l-icons/tier1-icons.html">
<d2l-icon icon="d2l-tier1:bookmark-filled"></d2l-icon>

The color will default to ferrite, and the size will be set automatically based on the category name.

To swap the color on-hover:

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:

<style is="custom-style">
d2l-icon.big-icon {
    --d2l-icon-height: 50px;
    --d2l-icon-width: 50px;
}
</style>
<d2l-icon class="big-icon" icon="..."></d2l-icon>

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 <img> element

Simply point an HTML <img> 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:

<img src="bower_components/d2l-icons/images/tier1/bookmark-filled.svg" alt="bookmarked" />

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:

<button>
    <span class="my-app-bookmark-icon"></span>
    Bookmark
</button>

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 component, or follow WebAIM's text-indent technique.

For example, a button which contains only an icon:

<link rel="import" href="../d2l-offscreen/d2l-offscreen.html">
<button title="Bookmark">
    <span class="my-app-bookmark-icon"></span>
    <d2l-offscreen>Bookmark</d2l-offscreen>
</button>

We've used the title attribute in this example to display tooltips on-hover.

Sass Mixins

If you'd like to use the Sass 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 in a CSS class for each of the icons you'd like to use:

@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.

<span class="my-app-bookmark-icon"></span>

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 <svg> element must:
  • have a width and height attribute which match the native size
  • not have an id or data-name attribute
• the <svg>'s viewBox attribute must:
  • have an origin beginning with 0 0
  • be exactly square (e.g. 0 0 18 18)
  • match the icon's native size
  • not contain negative values
• there should be no <title> element
• there should be no inline <style> -- all style for line fills should be applied directly to the SVG elements
• color of SVG elements should be "ferrite" (#494c4e)

The best way to have most of these rules applied for you automatically is to put the icon through SVGOMG with the "remove title" and "prettify code" options selected.

Here's a sample of a properly formatted SVG:

<svg width="18" height="18" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 18">
  <path fill="#494c4e" d="..."/>
</svg>

Auto-generated files

The Polymer iconset files and Sass icons.scss file are automatically generated, so when making icon modifications, re-generate these files by running npm run build.

Bidirectionality

When rendered in a right-to-left direction, any icons which show directionality in terms of time (back/forward, next/previous, etc.) need to be mirrored horizontally. If the underlying <svg> element has a mirror-in-rtl attribute set, the <d2l-icon> component will do this automatically.

<svg mirror-in-rtl="true" ...>
  ...
</svg>

To learn more about how best to determine if an icon should be mirrored, refer to Google's Material Design Bidirectionality documentation.

Versioning

Commits and PR merges to master will automatically do a minor version bump which will:

• Update the version in package.json
• Add a tag matching the new version
• Create a github release matching the new version

By using either [increment major] or [increment patch] notation inside your merge message, you can overwrite the default version upgrade of minor to the position of your choice.

Links

• View on GitHub
• Online Demo
• Documentation
• GitHub Homepage
• Issue tracker

Compatibility