search

indiana-university / rivet-icons

Icons for Indiana University's Rivet Design System
https://rivet.iu.edu/icons-stickers/
BSD 3-Clause "New" or "Revised" License
7 stars 6 forks source link

readme

Rivet Icons

Icons (16px square) for Indiana University's Rivet Design System.

Migrate from v2 to v3.

Contents

  1. Usage
  2. HTML API
  3. CSS API
  4. JavaScript API
  5. Request a new icon

Usage

Development

This approach is recommended for development, prototyping, or restrictive production environments.

Link to:

These files can be linked from a service like UNPKG.

<!doctype html>
<html lang="en">
    <head>
        <link rel="stylesheet" href="https://unpkg.com/rivet-icons/dist/rivet-icon-element.css">
        <script type="module" src="https://unpkg.com/rivet-icons/dist/rivet-icons.js"></script>
    </head>
    <body>
        <rvt-icon name="heart"></rvt-icon>
        <rvt-icon name="heart-solid"></rvt-icon>
    </body>
</html>

Production

For production, install the npm package.

npm install --save rivet-icons

Create a custom module which imports only the icons needed. The icon module name (such as ./dist/heart.js) matches its corresponding SVG file name (such as ./src/icons/heart.svg).

// ./src/icons.js
import 'rivet-icons/dist/heart.js';
import 'rivet-icons/dist/heart-solid.js';

Link to:

<!doctype html>
<html lang="en">
    <head>
        <link rel="stylesheet" href="https://github.com/indiana-university/rivet-icons/blob/develop/node_modules/rivet-icons/dist/rivet-icon-element.css">
        <script type="module" src="https://github.com/indiana-university/rivet-icons/raw/develop/src/icons.js"></script>
    </head>
    <body>
        <rvt-icon name="heart"></rvt-icon>
        <rvt-icon name="heart-solid"></rvt-icon>
    </body>
</html>

Accessibility

By default, stickers are considered decorative images and hidden from screen reader users.

Ask this question to test if alternative text is needed: "Would this content still make sense to sighted users if the icon was removed?" If no, then add alternative text using the Rivet class rvt-sr-only.

In this first example, the link text of "Favorites" is presented to all users. The icon acts as a visual anchor and perhaps a legend to the rest of the page. No additional accessible description is needed.

<a href="https://github.com/indiana-university/rivet-icons/blob/develop/favorites">
    <rvt-icon name="heart"></rvt-icon>
    Favorites
</a>

In this second example, this icon is used to visually indicate the pressed state of the button. It is "heart" if the button is not pressed. It is "heart-solid" if the button is pressed. aria-pressed communicates the necessary information to screen readers. This attribute value changes the icon via the CSS API in order to communicate equivalent information to visual users.

<button aria-pressed="true" class="favorite">
    <rvt-icon></rvt-icon>
    Favorite
</button>

In this case, even if a text label for sighted users is not wanted, it is required for screen reader users.

<button aria-pressed="true" class="favorite">
    <rvt-icon></rvt-icon>
    <span class="rvt-sr-only">Favorite</span>
</button>

Testing

Download or clone this repo, then install dependencies.

npm install

Start the server to launch the local test environment.

npm run start

HTML API

name attribute

Use the name attribute to declare the icon to be rendered. The name of an icon matches its corresponding SVG file name (./src/icons/*.svg).

<rvt-icon name="heart"></rvt-icon>

CSS API

--name variable

Change the icon in CSS by setting the --name variable on the rvt-icon element to the desired icon name, such as var(--heart) for the "heart" icon.

In this example, the button toggles the value of aria-pressed for screen reader users, while the icon updates between the solid heart and outlined heart for visual users.

<button aria-pressed="true" class="favorite">
    <rvt-icon></rvt-icon>
    Favorite
</button>
<style>
.favorite[aria-pressed="false"] > rvt-icon {
    --name: var(--heart);
}
.favorite[aria-pressed="true"] > rvt-icon {
    --name: var(--heart-solid);
}
</style>

The --name CSS variable declaration overrides the name HTML attribute. In this case, the icon will render as heart-solid, not heart.

<rvt-icon name="heart" class="heart-solid"></rvt-icon>
<style>
.heart-solid {
    --name: var(--heart-solid);
}
</style>

color property

Change the icon color with the CSS color property. It is recommended to use the Rivet color utility classes.

<rvt-icon name="heart" class="rvt-color-orange"></rvt-icon>

JavaScript API

registerIcon() function

If the provided icon set does not have an icon you need, first request a new icon from the Rivet team.

If you must proceed with designing your own SVG icon, follow these specifications so they best align with the provided icon set:

Use the registerIcon() function to register the name and SVG code for this custom icon. Then, it can be used like any of the provided icons.

// ./src/icon-diamond.js
import { registerIcon } from 'rivet-icons';

const name = 'diamond';
const svg = `<svg><polyline points="8,2 14,8 8,14 2,8" /></svg>`;

registerIcon(name, svg);

If left unspecified, the <svg> will default to the following attributes when rendered:

<svg
    aria-hidden="true"
    fill="currentColor"
    focusable="false"
    height="16"
    viewBox="0 0 16 16"
    width="16"
    xmlns="http://www.w3.org/2000/svg"
>

Include this custom icon in the module for the custom icon set.

// ./src/icons.js
import 'rivet-icons/dist/heart.js';
import 'rivet-icons/dist/heart-solid.js';
+ import './icon-diamond.js';

Request a new icon

Submit a Rivet support request to request a new icon.