UNPKG

6.21 kBMarkdownView Raw
1# Rivet Icons
2
3[Icons](https://rivet.iu.edu/icons-stickers/) (`16px` square) for Indiana University's Rivet Design System.
4
5[Migrate from v2 to v3](MIGRATION.md).
6
7## Contents
8
91. [Usage](#usage)
101. [HTML API](#html-api)
111. [CSS API](#css-api)
121. [JavaScript API](#javascript-api)
131. [Request a new icon](#request-a-new-icon)
14
15## Usage
16
17### Development
18
19This approach is recommended for development, prototyping, or restrictive production environments.
20
21Link to:
22
23- The Rivet Icon Element styles (`./dist/rivet-icon-element.css`)
24- The bundle containing all the icons (`./dist/rivet-icons.js`)
25
26These files can be linked from a service like [UNPKG](https://unpkg.com/browse/rivet-icons/).
27
28```html
29<!doctype html>
30<html lang="en">
31 <head>
32 <link rel="stylesheet" href="https://unpkg.com/rivet-icons/dist/rivet-icon-element.css">
33 <script type="module" src="https://unpkg.com/rivet-icons/dist/rivet-icons.js"></script>
34 </head>
35 <body>
36 <rvt-icon name="heart"></rvt-icon>
37 <rvt-icon name="heart-solid"></rvt-icon>
38 </body>
39</html>
40```
41
42### Production
43
44For production, install the npm package.
45
46```
47npm install --save rivet-icons
48```
49
50Create 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`).
51
52```js
53// ./src/icons.js
54import 'rivet-icons/dist/heart.js';
55import 'rivet-icons/dist/heart-solid.js';
56```
57
58Link to:
59
60- The Rivet Icon Element styles (`./dist/rivet-icon-element.css`)
61- The custom module (for example, `./src/icons.js`)
62
63```html
64<!doctype html>
65<html lang="en">
66 <head>
67 <link rel="stylesheet" href="./node_modules/rivet-icons/dist/rivet-icon-element.css">
68 <script type="module" src="./src/icons.js"></script>
69 </head>
70 <body>
71 <rvt-icon name="heart"></rvt-icon>
72 <rvt-icon name="heart-solid"></rvt-icon>
73 </body>
74</html>
75```
76
77### Accessibility
78
79By default, stickers are considered decorative images and hidden from screen reader users.
80
81Ask 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`.
82
83In 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.
84
85```html
86<a href="/favorites">
87 <rvt-icon name="heart"></rvt-icon>
88 Favorites
89</a>
90```
91
92In 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.
93
94```html
95<button aria-pressed="true" class="favorite">
96 <rvt-icon></rvt-icon>
97 Favorite
98</button>
99```
100
101In this case, even if a text label for sighted users is not wanted, it is required for screen reader users.
102
103```html
104<button aria-pressed="true" class="favorite">
105 <rvt-icon></rvt-icon>
106 <span class="rvt-sr-only">Favorite</span>
107</button>
108```
109
110### Testing
111
112Download or clone this repo, then install dependencies.
113
114```
115npm install
116```
117
118Start the server to launch the local test environment.
119
120```
121npm run start
122```
123
124## HTML API
125
126### `name` attribute
127
128Use the `name` attribute to declare the icon to be rendered. The name of an icon matches its corresponding SVG file name (`./src/icons/*.svg`).
129
130```html
131<rvt-icon name="heart"></rvt-icon>
132```
133
134## CSS API
135
136### `--name` variable
137
138Change 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.
139
140In 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.
141
142```html
143<button aria-pressed="true" class="favorite">
144 <rvt-icon></rvt-icon>
145 Favorite
146</button>
147<style>
148.favorite[aria-pressed="false"] > rvt-icon {
149 --name: var(--heart);
150}
151.favorite[aria-pressed="true"] > rvt-icon {
152 --name: var(--heart-solid);
153}
154</style>
155```
156
157The `--name` CSS variable declaration overrides the `name` HTML attribute. In this case, the icon will render as `heart-solid`, not `heart`.
158
159```html
160<rvt-icon name="heart" class="heart-solid"></rvt-icon>
161<style>
162.heart-solid {
163 --name: var(--heart-solid);
164}
165</style>
166```
167
168### `color` property
169
170Change 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/).
171
172```html
173<rvt-icon name="heart" class="rvt-color-orange"></rvt-icon>
174```
175
176## JavaScript API
177
178### `registerIcon()` function
179
180If the provided icon set does not have an icon you need, first [request a new icon](#request-a-new-icon) from the Rivet team.
181
182If you must proceed with designing your own SVG icon, follow these specifications so they best align with the provided icon set:
183
184- `16px` square grid
185- `2px` stroke for all icon outlines
186- Expand all strokes before exporting and merge/flatten artwork in to one group.
187- Set `fill` attribute to `currentColor` on exported SVGs.
188
189Use 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.
190
191```js
192// ./src/icon-diamond.js
193import { registerIcon } from 'rivet-icons';
194
195const name = 'diamond';
196const svg = `<svg><polyline points="8,2 14,8 8,14 2,8" /></svg>`;
197
198registerIcon(name, svg);
199```
200
201If left unspecified, the `<svg>` will default to the following attributes when rendered:
202
203```html
204<svg
205 aria-hidden="true"
206 fill="currentColor"
207 focusable="false"
208 height="16"
209 viewBox="0 0 16 16"
210 width="16"
211 xmlns="http://www.w3.org/2000/svg"
212>
213```
214
215Include this custom icon in the module for the custom icon set.
216
217```diff
218// ./src/icons.js
219import 'rivet-icons/dist/heart.js';
220import 'rivet-icons/dist/heart-solid.js';
221+ import './icon-diamond.js';
222```
223
224## Request a new icon
225
226[Submit a Rivet support request](https://rivet.uits.iu.edu/help/#support-request-form) to request a new icon.