Skip to content

Latest commit

 

History

History
127 lines (88 loc) · 7.12 KB

README.md

File metadata and controls

127 lines (88 loc) · 7.12 KB
Raw

Icons

The <d2l-icon> web component can be used in your applications to embed one of the roughly 500 preset SVG icons that make up the Brightspace iconography set.

For custom SVGs not part of our iconography set, use the <d2l-icon-custom> web component.

Preset Icons

For preset icons, import and use the <d2l-icon> web component with the icon attribute.

<script type="module">
  import '@brightspace-ui/core/components/icons/icon.js';
</script>
<d2l-icon icon="tier1:gear"></d2l-icon>

The icon attribute value is of the form <category-name>:<icon-name>. The icon will automatically be the correct color (Tungsten) and size based on its category.

Note: Always choose the icon whose native size best matches your desired icon size, ideally exactly.

Category Name Description Samples Size List
tier1 minimal level of detail, solid style print   gear   save 18px x 18px Full set
tier2 medium level of detail, linear style audio   copy   news 24px x 24px Full set
tier3 medium level of detail, linear style notifications   help   search 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

Custom SVG Icons

To use a custom SVG icon, embed the SVG inside a <d2l-icon-custom> element and set the size attribute to one of: tier1, tier2 or tier3.

<script type="module">
  import '@brightspace-ui/core/components/icons/icon-custom.js';
</script>
<d2l-icon-custom size="tier1">
  <svg width="18" height="18" viewBox="0 0 18 18" xmlns="http://www.w3.org/2000/svg">
    <path fill="#494c4e" d="..."/>
  </svg>
</d2l-icon-custom>

Ensure that the SVG is formatted according to the rules outlined below.

Overriding the Color

To change an icon's color from Tungsten to something else, simply set it from CSS:

<d2l-icon icon="tier3:alert" style="color: red;"></d2l-icon>

Overriding the Size

Overriding the size is not recommended. However, if you must, set the width and height from CSS.

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 manageable, only icons that have the potential to be reused many times should be a part of this collection.

SVG format

When contributing changes to icons, the SVG files should be properly formatted. This ensures that they will render at the correct size and in the correct color across all browsers. 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 at 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 "tungsten" (#494c4e)

The best way to have most of these rules applied for you automatically is to put the icon through SVGOMG with these options selected:

  • Prettify code - ON
  • Remove viewBox - OFF
  • Remove <title> - ON

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 catalogue.md catalogue file is automatically generated. When making icon modifications, re-generate this file by running npm run build:icons.

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.

File Icon Type Helper

Helper functions that return a file icon type based on the given file extension or filename string. Returns string of form file-{type}, corresponding to an icon name for the <d2l-icon> component.

import { getFileIconTypeFromExtension, getFileIconTypeFromFilename } from '@brightspace-ui/core/components/icons/getFileIconType.js';

getFileIconTypeFromExtension('docx'); // returns 'file-document'
getFileIconTypeFromFilename('MY_SONG.MP3'); // returns 'file-audio'

Future Enhancements

Looking for an enhancement not listed here? Create a GitHub issue!