@alaskaairux/icons

    4.8.4 • Public • Published

    Auro Icon Library

    The focus of this repository is to manage, at scale, the enterprise need for icons in the new Auro Design System and deprecate any legacy items. Please see all supporting documentation for contributing to, and consuming icons from this SVG icon library.

    Install

    Build Status See it on NPM! License

    $ npm i @alaskaairux/icons

    Sass styles for IE fallback

    For use in situations where CSS custom properties are not supported. In the dist/ directory is icons.scss. Import this Sass file for default shape styles.

    @import '@alaskaairux/icons/dist/icons';

    Within React, Sass requires a ~ character prior to the importing library, example:

    @import '~@alaskaairux/icons/dist/icons';

    Due to dependency on Auro tokens, be sure to import the Sass variables prior to importing the Icons selectors.

    @import "~@alaskaairux/orion-design-tokens/dist/tokens/SCSSVariables";

    Using Icons/Tokens within a LitElement Custom Element

    When using Icons within the scope of a LitElement Custom Element, the CSSTokenProperties.css file can to be referenced within the scope of the shadow DOM. To do this, the CSS needs to be wrapped in a JavaScript module.

    Add the following line to the head of the Custom Element document:

    import iconProperties from '@alaskaairux/icons/dist/tokens/CSSTokenProperties-css.js';

    Within the render(), then within the return html template literal, add the following:

    ${iconProperties}

    This will insert the Token output within the scope of the shadow DOM Custom Element and render the appropriate values per the CSS Custom Properties.

    Using Icon Properties outside the shadow DOM

    When using an icon, it is not necessary to load the Icon CSS custom properties within the scope of the shadow DOM. As long as the variables are made available from the global scope of the project, the CSS custom properties will pierce the shadow DOM and style the icons.

    Icon categories

    Icons fall into a series of use categories, these are:

    category description
    alert Icons used specifically to alert users as to the state of awareness
    in-flight icons reserved for 'day of travel' user experiences
    interface Icons used to create interface enhancements
    payment Icons specifically to be used in a transaction flow
    shop icons for use with shopping experiences
    social Icons for use with social media
    terminal Icons related to terminal experiences

    Node application dependency

    Via a node.js dependency or other node like dependency management architecture, developers can choose from two different scenarios for the rendering of the SVG. This technique will render the SVG inline from the designated resource location.

    Individual icon request

    It is suggested that developers list individual dependencies per UI component, like so:

    const warning = require('@alaskaairux/icons/dist/icons/alert/warning');

    Within the UI component a developer can reference the object assigned to the newly created variable to get the specific icon's SVG code:

    <button>Click Me ${warning.svg}</button>

    This will return the icon's SVG HTML inline.

    Individual logo request

    It is suggested that developers list individual dependencies per UI component, like so:

    const alaskaLogo = require('@alaskaairux/icons/dist/logos/glyph-AS');

    Within the UI component a developer can reference the object assigned to the newly created variable to get the specific logo's SVG code:

    <div>${alaskaLogo.svg}</div>

    This will return the icon's SVG HTML inline.

    Altering the SVG output

    Using either method, the SVG is captured as an object that can be manipulated. For example, calling the warning.js file as shown below ...

    const warning = require('@alaskaairux/icons/dist/icons/alert/warning');

    ... will output the following HTML

    <svg role="img" aria-hidden="true" style="fill: currentcolor; width: var(--auro-size-lg);  height: var(auro-size-lg)" class="ico_squareLarge" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
      <title>Warning</title>
      <g>
        <polygon points="4 4 0 0 8 0"></polygon>
      </g>
    </svg>

    Adding the following line of JavaScript will find and replace the aria-hidden attribute in the warning.svg string ...

    warning.svg = warning.svg.replace(/aria-hidden="true"/g, `aria-hidden="false"`);

    ... and then output the following:

    <svg role="img" aria-hidden="false" style="fill: currentcolor; width: var(--auro-size-lg);  height: var(--auro-size-lg)" class="ico_squareLarge" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
      <title>Warning</title>
      <g>
        <polygon points="4 4 0 0 8 0"></polygon>
      </g>
    </svg>

    JavaScript framework support

    When using other JavaScript development frameworks, the process above may not parse to HTML. To address this, there are a few techniques that could be used.

    Within the npm, @alaskaairux/icons/dist/icons/, developers may access the SVGs directly for consumption into the development environment.

    JS versions of SVGs

    This repo output two types of JS wrapped SVGs for easy inclusion with front-end frameworks.

    Default style - iconName.js

    module.exports={ ... }

    ES6 style - iconName_es6.js

    export default { ... }

    In most cases, the default exported JS file will work. But in some cases, the ES6 style module export is required. Simply point to the resource needed for use.

    Lit-element

    Lit-element requires the ES6 module export syntax for use, so an example dependency reference would be:

    import warning from '@alaskaairux/icons/dist/icons/alert/warning_es6.js';

    Parsing out the SVG HTML to become DOM requires lines of code within the scope of the new custom element class, for example:

    constructor() {
      this.dom = new DOMParser().parseFromString(warning.svg, 'text/html');
      this.svg = this.dom.body.firstChild;
    }

    Now that the SVG DOM is assigned to the this.svg variable, rendering this within the HTML render() template could be like the following:

    <p>${this.svg}</p>

    Web Component

    The easiest use of Auro Icons is to use the auro-icon web component. See the following HTML with attribute API examples. See the Auro site for more details on use.

    <auro-icon category="" name="" [optional state]>[optional description]</auro-icon>

    React

    React supports a standard for linking to assets and using them within the context of a component.

    import warning from '@alaskaairux/icons/dist/icons/alert/warning.svg';

    Within the component's render() function, passing in the new variable into the src attribute of an <img> element will render the asset.

    <img src={warning} alt="warning" />

    SVG React Loader

    Using svg-react-loader in combination with webpack will render the SVG inline from the designated resource location.

    import warning from '-!svg-react-loader!@alaskaairux/icons/dist/icons/alert/warning.svg';

    Within the component's render() function, simply reference the new component that is generated via svg-react-loader.

    <warning />

    With SVG React Loader, users are also able to over-ride attributes within the SVG. For example, the following code illustrates how a user could over-ride the role="img" and aria-hidden="true" attributes:

    <warning role="group" aria-hidden="false"/>

    Note: eslint support

    The above syntax may cause issues with your eslint configurations. The following error may appear:

    Unexpected '!' in '-!svg-react-loader?name=Icon!@alaskaairux/icons/dist/icons/alert/warning.svg'. Do not use import syntax to configure webpack loaders

    In this event, adding the following comments within the component may address the issue:

    // eslint-disable-next-line import/no-webpack-loader-syntax
    import Arrowdown from '-!svg-react-loader?name=Icon!@alaskaairux/icons/dist/icons/alert/warning.svg';

    Adding new icons

    Adding new icons to this repository requires a few steps.

    1. Node.js minimum version 12.x
    2. Add a new icon .svg file to the src/icons/ directory (see Guidelines below)
    3. If the icons are to retain designed color specs, please place the new icon in the src/icons/fullColor directory
    4. Add shape schema to ./src/data/icons.json file (see example below)
    5. Submit pull request for approval

    Icon shape schema

    When adding new icons, be sure to follow the example below to add the proper data to the icons.json file. Any attribute defined in the "commonProperties" object may be over-written in the individual "icons" object.

    Default attributes for each SVG

    key type default description
    color string currentcolor sets CSS property of color to currentcolor
    height string var(--auro-size-lg) sets CSS property of height to var(--auro-size-lg)
    hidden boolean true sets HTML attribute hidden to true for a11y
    path string /icons sets path for pre-build icon; icons that require full color spec, use "path": "/icons/fullColor"
    role string img sets aria role to img
    style string ico_squareLarge value is applied to SVG as CSS class attribute
    viewbox string 0 0 24 24 sets SVG attribute to default shape
    width string var(--auro-size-lg) sets CSS property of width to var(--auro-size-lg)
    xmlns string http://www.w3.org/2000/svg sets xmlns SVG attribute
    xmlns_xlink string http://www.w3.org/1999/xlink sets xmlns SVG attribute

    Required attributes for each SVG

    key type default description
    name string The name of the svg file
    category string Defines categorical placement of the icon
    desc string The <desc> element provides an accessible, long-text description of any SVG

    Optional attributes for each SVG

    key type default description
    title string The <title> element provides an accessible, short-text description of any SVG, may appear as a tool-tip in the browser; can be derived from the file name

    The title attribute is needed when you may want a simpler name than the file name. In the example data below, there is the information-stroke.svg, but the name information-stroke is meaningless if rendered to the browser. Updating the title to simply be information will address that.

    Example data

    {
      "commonProperties":
      {
          "hidden": "true",
          "role": "img",
          "color": "currentColor",
          "width": "var(--auro-size-lg)",
          "height": "var(--auro-size-lg)",
          "xmlns": "http://www.w3.org/2000/svg",
          "xmlns_xlink": "http://www.w3.org/1999/xlink",
          "viewBox": "0 0 24 24",
          "path": "/icons",
          "style": "ico_squareLarge"
      },
      "icons": [
        {
          "name": "error",
          "desc": "Error alert indicator",
          "category": "alert"
        },
        {
          "title": "Information",
          "name": "information-stroke",
          "desc": "Important information indicator",
          "category": "alert"
        }
      ]
    }

    Discouraged: For color and width do not use hard-coded values. To be compliant you must use Auro Design Token references.

    Test new icon SVG code

    Once the new icon has been added to the icons directory and the icon data JSON file has been updated, run the following commands.

    $ npm run generate
    $ npm run serve
    

    As update are made, simply run $ npm run generate to generate a new series of icons and rebuild the demo page.

    Publish static demo page

    All the resources needed to deploy a static demo page are in the ./demo directory.

    Icon guidelines

    All new icon pull requests MUST comply with the following specifications. Any pull-request that does not follow these specifications will be considered non-compliant and will be rejected.

    1. icon.svg file names must be camelCased, no spaces, dashes or underscores
    2. SVG code should be the minimal code to render the SVG

    DO

    Please reduce the SVG HTML to only the following attributes. The build process will scrub away any unwanted attributes from the SVG file.

    <svg>
      <g>
        <polygon points="43.9886686 48 24 27.9721836 4.01133144 48 0 44.0611961 19.9886686 23.9666203 0.0679886686 3.93880389 4.14730878 0 24 19.961057 43.8526912 0 47.9320113 3.93880389 27.9433428 23.9666203 48 44.0611961"></polygon>
      </g>
    </svg>

    DO NOT

    Please do not include unnecessary specifications, attributes, spaces and returns in the HTML as they will be scrubbed away in the build process. Anything not manually removed or scrubbed will fail the svglint tests.

    1. xml version
    2. width or height hard coded HTML attributes
    3. Any auto generated comments
    4. Description, unless title is unable to describe the intent of the SVG image/icon
    5. Any IDs, stroke or fill attributes, unless required for the complexity of the SVG image/icon
    <?xml version="1.0" encoding="UTF-8"?>
    <svg width="8px" height="4px" viewBox="0 0 8 4" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
        <!-- Generator: Sketch 52.5 (67469) - http://www.bohemiancoding.com/sketch -->
        <title>Arrow Down</title>
        <desc>Created with Sketch.</desc>
        <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
            <g id="Arrow-Down" fill="#0074C8">
                <polygon id="Path" points="4 4 0 0 8 0"></polygon>
            </g>
        </g>
    </svg>

    Thanks!

    This project was forked from, and inspired by simple-icons. On the shoulder's of giants, open-source projects help and inspire us all to do better things!

    Install

    npm i @alaskaairux/icons

    DownloadsWeekly Downloads

    8,790

    Version

    4.8.4

    License

    Apache-2.0

    Unpacked Size

    7.1 MB

    Total Files

    799

    Last publish

    Collaborators

    • alaskaairux