icons
SVGs, Polymer web components and SASS mixins for D2L icons
[ 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
andheight
attribute which match the native size - not have an
id
ordata-name
attribute
- have a
- the
<svg>
'sviewBox
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
- have an origin beginning with
- 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
Compatibility
Was this helpful? Need more help?
Leave a comment or a question below. You can also join
the chat on Discord or
ask questions on StackOverflow.
Version
Dependencies
- d2l-colors#^3.1.2
- iron-iconset-svg#^2.1.0
- polymer#1.9 - 2
- Released
- 2019-05-17
- Maturity
- IMPORTED
- License
- Apache License 2.0
Compatibility
- Framework
- Polymer 2.0+
- Polymer 1.0+ in 3.9.0
- Browser
- Browser Independent