@cagov/ds-icons

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

• 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 Contributors Documentation

Icon library

Version 5.6.2 of the CAGov icon library. Download individual svgs using the links below.

{% include 'layouts/icon-library.njk' %}