@heroku/ember-malibu-icon

Ember Malibu Icon

This Ember addon injects the Malibu svg sprite into your Ember application and provides a helper to insert icons into your templates. You can explore how this helper works in this addon's demo app and documentation.

Note that it will be helpful if you also use Purple 3 for styling

Installation

ember install --save @heroku/ember-malibu-icon

Configuration

By default this addon will inject the latest version of Malibu. Consumers can configure this in their application's config/environment.js file

ENV['ember-malibu-icon'] = {
  malibuVersion: '1.3.0'
}

Ember Template Lint Rules

Ember Malibu Icon also comes with a bunch of handy Ember Template Lint rules to help remind you to declare accessibility options when possible.

To use these lint rules in your app, add the following to your .template-lintrc.js file:

module.exports = {
  extends: [
    'recommended',
    '@heroku/ember-malibu-icon:recommended'
  ],
  plugins: [
    require('@heroku/ember-malibu-icon/lib/ember-template-lint-plugin')
  ]
};

The documentation for each rule can be found in the docs/rules directory folder of this project.

Usage

From a Handlebars (.hbs) file

Accessibility

Accessibility When rendering MalibuIcon, you must declare the icon as either:

• informational: Pass a non-empty string to @title argument. This will read the text to the screenreader instead of being announced as "Image".
• decorative: Pass aria-hidden="true" to the component. This will hide the icon from assistive technology. This should only be used for icons that don't convey additional meaning and are being used for aesthetic/design reasons.

Informational Usage Example

Use this when when you want text to be announced to the screenreader. This is most common when you have icons that are used for buttons or links but lack text rendered next to the icon to describe it.

<MalibuIcon @title="Add Buildpack {{buildpackName}}" @size="28" @iconClass="gradient-dark-gray" @name="app-28" />

For example:

Given this screenshot, note the pencil icon. There is no text next to it to describe its intended purpose to the screenreader (in this case, "Edit"). @title="Edit {{domain}}" would be an improvement in this scenario.

Decorative Usage

Use this when the icon does not convey additional meaning. There should be visual text accompanying the icon. Never use this when only the icon is rendered.

• Ember.js v3.12 or above
• Ember CLI v2.13 or above
• Node.js v10 or above

In this example, the GitHub logo is "decorative" because it does not convey additional meaning not already presented to the user via the "GitHub" text next to it.

<MalibuIcon @size="28" @iconClass="gradient-dark-gray" @name="app-28" aria-hidden="true" />

From a javascript file (not recommended/deprecated)

import { malibuIcon } from '@heroku/ember-malibu-icon/helpers/malibu-icon';
malibuIcon({
  name: 'app-16',
  size: 16,
  iconClass: 'v-mid gradient-purple',
  title='Optional Title'
})

Development

• git clone https://github.com/heroku/ember-malibu-icon
• cd ember-malibu-icon
• yarn

Running

• ember serve
• Visit your app at http://localhost:4200.

Running Tests

• yarn test (Runs ember try:each to test your addon against multiple Ember versions)
• ember test
• ember test --server

Building

• ember build

For more information on using ember-cli, visit https://ember-cli.com/.

Releases

Notes

This library does its best to follow the principles of Semantic Versioning. Every effort should be made to ensure all non-major versions are released in a backwards compatible way.

Making a New Release

Once you are ready to make a new release follow these steps:

• Create a new branch
• Update the version number in package.json
• Commit your changes and open a PR

Publish your new version to npm with the command npm publish 🎉

Note that you must have publish access to the @heroku npm organization to successfully publish