@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

Malibu version

By default the addon loads the latest Malibu sprite. To pin a specific version, set ENV['ember-malibu-icon'] in your app's config/environment.js:

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

Mirage JS

If your app uses Mirage JS for API mocking, you'll need to configure it to allow requests to the Malibu CDN. Add this to your mirage/config.js:

export default function () {
  // ... your existing routes

  // Allow Malibu sprite requests to pass through to CDN
  this.passthrough('https://www.herokucdn.com/malibu/**');
}

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.

Compatibility

• Ember.js 3.28 or above (see versionCompatibility in package.json)
• Works with both Embroider and classic Ember builds
• Node.js 20 or above

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.

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
• pnpm install

Running

• pnpm start
• Visit your app at http://localhost:4200.

Running Tests

• pnpm test (Runs the demo app build and Ember tests via Testem)
• pnpm test:ember-template-lint (Runs the template lint rule tests)

Building

• pnpm build (Builds the addon with Rollup; also runs automatically on prepare and prepack)

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
• When the PR is merged, create a GitHub release
  • Releases -> Draft a new release
  • Select tag -> Create a new tag
  • Name the tag the same as the version e.g. v4.1.3 (this should match what's in the package.json)
  • Click Generate release notes
  • Save draft
  • Review the draft then Publish release

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