rivet-icons

# Rivet Icons [Icons](https://rivet.iu.edu/icons-stickers/) (`16px` square) for Indiana University's Rivet Design System. [Migrate from v2 to v3](MIGRATION.md). ## Contents 1. [Usage](#usage) 1. [HTML API](#html-api) 1. [CSS API](#css-api) 1. [JavaScript API](#javascript-api) 1. [Request a new icon](#request-a-new-icon) ## Usage ### Development This approach is recommended for development, prototyping, or restrictive production environments. Link to: - The Rivet Icon Element styles (`./dist/rivet-icon-element.css`) - The bundle containing all the icons (`./dist/rivet-icons.js`) These files can be linked from a service like [UNPKG](https://unpkg.com/browse/rivet-icons/). ```html <!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`). ```js // ./src/icons.js import 'rivet-icons/dist/heart.js'; import 'rivet-icons/dist/heart-solid.js'; ``` Link to: - The Rivet Icon Element styles (`./dist/rivet-icon-element.css`) - The custom module (for example, `./src/icons.js`) ```html <!doctype html> <html lang="en"> <head> <link rel="stylesheet" href="./node_modules/rivet-icons/dist/rivet-icon-element.css"> <script type="module" src="./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. ```html <a href="/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](#--name-variable) in order to communicate equivalent information to visual users. ```html <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. ```html <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`). ```html <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. ```html <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`. ```html <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](https://rivet.uits.iu.edu/utilities/color/). ```html <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](#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: - `16px` square grid - `2px` stroke for all icon outlines - Expand all strokes before exporting and merge/flatten artwork in to one group. - Set `fill` attribute to `currentColor` on exported SVGs. 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. ```js // ./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: ```html <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. ```diff // ./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](https://rivet.uits.iu.edu/help/#support-request-form) to request a new icon.