@cagov/ds-icons
v1.0.1
Published
A utility component for mangaging CA State Template v5.6.1 icons in the Design System.
Downloads
60
Keywords
Readme
Icons
Icons are visual cues that help people find key information and common actions. They visually represent:
- An idea or thing
- What something does
- How someone can interact with it
Icons reduce cognitive load by communicating meanings or actions simply and accurately.
When and how to use it
Use icons as visual indicators to make key actions or information easy to find. Organize content strategically before using icons. Choose an existing icon from Version 5.6.2 of the CAGov icon library whenever possible.
Use icons for the same purpose consistently to avoid confusion for visitors and reduce cognitive load. Select an icon that’s as closely tied to the specific information or action as possible. When it may not be clear what the icon means, pair it with a label or supporting text.
The Design System uses a standard set of icons for common actions. Several components incorporate icons automatically. This ensures consistency, and fewer steps for content designers. Some examples include:
- Expand icon in the accordion
- Hamburger icon in the site navigation menu for mobile devices
- External and pdf link icons in the link icon
- Social media icons in the site footer
- Up arrow icon in the back to top button
For a page alert, choose an icon that supports the tone of the alert.
How not to use it
Do not use an icon:
- That does not relate to the meaning or action
- Without a label if it is not widely understood
- For more than one function or concept
- Where an image or graphic is more appropriate
- For decoration
- If it creates visual clutter (like using too many on a page)
- As a shortcut to guide visitors to important information without structuring content strategically
Specs
| Property | Value | | ------------ | -------- | | Machine name | ds-icons | | JavaScript | yes |
Project installation
Method 1
Minimal sprite and JavaScript
Recommended for projects that use 10 - 200 icons.
The instructions assume familiarity with npm package management tool, modern JavaScript techniques, and Sass.
Identify all the icons you will need for your project by id using the Icon library below.
npm install @cagov/ds-icons
Run the command
npm run dev:sprite-some [ids]
to generate a the sprite- Example:
npm run dev:sprite-some gear arrow-down left
- Example:
The generated sprite will be called
cagovSomeIcons.svg
.Include the generated sprite and ./index.js as a module in your project or page.
Place individual icon inline with
<cagov-icon data-icon="[id]"></cagov-icon>
Demo and sample markup
<div
style="display:grid; grid-template-columns: 1fr 1fr; grid-gap: 20px; text-align: center;"
>
<!--Decorative-->
<cagov-icon data-icon="arrow-down"></cagov-icon>
<cagov-icon data-icon="drive"></cagov-icon>
<!--Functional-->
<cagov-icon data-icon="gear" data-sr="Settings"></cagov-icon>
<cagov-icon data-icon="left" data-sr="Next Page"></cagov-icon>
</div>
Method 2
Direct download and include.
Recommended for projects that use 1-9 icons.
Identify the icon(s) you will need for your project by id using the Icon library below.
Click the Download link.
Copy/paste or reference the icon in your project.
Method 3
Icon font and CSS.
Recommended for projects where content authors need to be able to add any font inline using only HTML.
Copy the
src/fonts
folder to your web app.Copy the
src/icon-font.css
file to your web app.Include the CSS in your project or page. The CSS must be at the same directory level as the
fonts
folder.Place individual icon in HTML using
<span class="ca-gov-icon-[id]" aria-hidden="true"></span>
Demo and sample markup
<span class="ca-gov-icon-audio" aria-hidden="true"></span>
<span class="ca-gov-icon-drive" aria-hidden="true"></span>
<span class="ca-gov-icon-ferry" aria-hidden="true"></span>
<span class="ca-gov-icon-van" aria-hidden="true"></span>
Accessibility recommendations
Component-specific accessibility review
These icons are decorative by default and use the aria-hidden
attribute. Associated text can be made available to screen readers using Method 1 and the attribute pattern data-sr="My descriptive text."
When using Methods 2 and 3, be mindful of accessibility best practices.
Standard accessibility review
As a component in Alpha status, this component must pass the following accessibility reviews every time a new version is published:
- Tested with the axe accessibility tool and passes all automated WCAG Level AA checks
- Reviewed with the VoiceOver screen reader on desktop
- Verified keyboard navigation and that all actionable elements of the component are reachable via keyboard commands only
- Reviewed component layout on a variety of screen sizes
Contributor/developer documentation
Icon library
Version 5.6.2 of the CAGov icon library. Download individual svgs using the links below.
{% include 'layouts/icon-library.njk' %}