Skip to main content

CHASSIS ICONS

Multi-Format Icon Distributionfor Chassis Design Systems

Ship icons as SVG sprites, web fonts, or direct imports. Automated builds generate optimized assets with CSS/SCSS, compatible with any platform or framework.

git clone git@github.com:chassis-ui/tokens.git
Get StartedView on GitHub

Currently v0.3.1·Changes

Build

Get started with Chassis Icons in just a few steps. Save your icon files, build the icons, and import the CSS stylesheet to your project.

Save Files

Store your icon files in organized directories for easy access.

svgs/
├── icon-file.svg
├── icon-file.svg
├── icon-file.svg
└── ...

Build Icons

Use the build scripts to generate icon fonts and CSS.

# Build icons
pnpm icons

# Build doc pages
pnpm site:pages

Import Files

Integrate the icon library by importing the CSS stylesheet.

<!-- HTML -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/chassis-icons@0.3.1/font/chassis-icons.min.css">
/* CSS */
@import url("https://cdn.jsdelivr.net/npm/chassis-icons@0.3.1/font/chassis-icons.min.css");

Sprite

Usage

Chassis Icons are SVGs, so you can include them into your HTML in a few ways depending on how your project is setup. We recommend using using sprite and customize its color by changing --cx-icon-size and -cx-icon-color. Those values are --cx-icon-medium and --cx-default-icon-main by default. Icon utilities are also available as .icon-* classes both for size and context base colors.

Sprite

Use the SVG sprite to insert any icon through the <use> element. Use the icon's filename as the fragment identifier (e.g., icon-name is #icon-name). SVG sprites allow you to reference an external file similar to an <img> element, but with the power of currentColor for easy theming.

Heads up! There's an issue with Chrome where <use> doesn't work across domains.

HTML
<svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>

External image

Copy the Chassis Icons SVGs to your directory of choice and reference them like normal images with the <img> element. Icon color could not be changed in this way.

Chassis
HTML
<img src="/static/icons/info-circle-solid.svg" alt="Chassis" width="24" height="24">

Icon font

Icon fonts with classes for every icon are also available in Chassis Icons. Include the icon web fonts in your page via CSS, then reference the class names as needed in your HTML.

Use font-size and color to change the icon appearance.

HTML
<span class="icon cx-info-circle-solid" aria-hidden="true"></span>

Styling

Easily style icons with Chassis CSS. Icons use --cx-icon-size and --cx-icon-color for their size and color. You can change those values in different ways.

Utilities

You can use icon-* classes to change both their size and colors. Put any context color or icon size after.

HTML
<svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
          <svg class="icon icon-info icon-xlarge" aria-hidden="true"><use href="#info-circle-solid"></use></svg>

Adaptive

Put .icon-adaptive and.icon-reset to change their values to --cx-font-size and --cx-fg-color.

Heading

HTML
<h2 class="fg-subtle">
  <svg class="icon icon-adaptive icon-reset" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
  Heading
</h2>

Context Colors

Icons color and sizes fit to context and components automatically. Context object color utilities are also available. Put .*-icon-main or .*-icon-subtle classes to change their color ad fill-color properties directly with an !important flag.

Note that, .icon-primary and .primary-icon-main are different colors. While .primary-icon-main using --cx-primary-icon-main color, .icon-primary uses --cx-primary-base-color for its property.

HTML
<div class="context secondary p-medium">
    <svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
    <svg class="icon icon-subtle icon-medium" aria-hidden="true"><use href="#info-circle-solid"></use></svg>

    <span class="icon cx-info-circle-solid fg-subtle icon-2xlarge" aria-hidden="true"></span>
    <span class="icon cx-info-circle-solid primary-icon-main" aria-hidden="true"></span>
    <span class="icon cx-info-circle-solid primary-fg-main icon-xsmall" aria-hidden="true"></span>
  </div>

CSS

You can also use the SVG within your CSS (be sure to escape any characters, such as # to %23 when specifying hex color values). When no dimensions are specified via width and height on the <svg>, the icon will fill the available space.

The viewBox attribute is required if you wish to resize icons with background-size. Note that the xmlns attribute is required.

Note that, it is not possible to change color if SVG used as background-image. Because of this, we prefer to use mask-image if any CSS usage needed.

CSS
.icon-bg::before {
  display: inline-block;
  content: "";
  vertical-align: -.125em;
  background-image: url("data:image/svg+xml,<svg viewBox='0 0 24 24' fill='%23ff5b14' xmlns='http://www.w3.org/2000/svg'><path fill-rule='evenodd' d='M8 9.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3z' clip-rule='evenodd'/></svg>");
  background-repeat: no-repeat;
  background-size: 1rem 1rem;
}
CSS
.icon-mask::before {
  position: absolute;
  width: 1rem
  height: 1rem
  margin-top: 0;
  margin-left: .5rem;
  content: "";
  background-color: #ff5b14;
  mask-image: url("data:image/svg+xml,<svg viewBox='0 0 24 24' fill='currentColor' xmlns='http://www.w3.org/2000/svg'><path fill-rule='evenodd' d='M8 9.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3z' clip-rule='evenodd'/></svg>");
  mask-position: center;
  mask-size: 1rem 1rem;
}

Accessibility

Icons are a great way to add visual interest to your site, but they can also be a barrier to accessibility if not used correctly. Here are some tips for making sure your icons are accessible to all users.

Image Alt Text

When using icons as images, it's important to provide an alt attribute that describes the icon's purpose. This is especially important for screen readers, which will read the alt text to users who cannot see the icon.

Chassis
HTML
<!-- alt="..." on <img> element -->
<img ... alt="Example icon" />

ARIA Label

When using icons, it's important to provide a text alternative for screen readers. This can be done using the aria-label attribute on the icon itself, or by providing a visually hidden text label that describes the icon's purpose.

HTML
<svg class="icon" ... role="img" aria-label="Example Icon">
  <use xlink:href="chassis-icons.svg#info-circle-solid"/>
</svg>

ARIA Hidden

When using icons as decorative elements, it's important to hide them from screen readers. This can be done using the aria-hidden attribute on the icon itself. This tells screen readers to ignore the icon and not announce it to users.

HTML
<!-- aria-label="..." on the control -->
<button ... aria-label="Example">
  <svg class="icon" aria-hidden="true" ...>
  ...
  </svg>
</button>

Working with SVGs

SVGs offer powerful flexibility for icon systems, but require specific implementation considerations for accessibility and cross-browser compatibility. The issues below address known platform quirks that aren't included in our default markup.

Focus in Legacy Browsers

SVG elements receive keyboard focus by default in Internet Explorer and Edge Legacy. Add `focusable="false"` to prevent this behavior.

View solution on Stack Overflow →

Screen Reader Announcements

When using <img> elements with SVG sources, screen readers may skip the image or fail to announce it properly. Include role="img" on the element.

Read accessibility guidance →

External Sprite Support (IE)

External SVG sprites using <use> with href attributes don't work in Internet Explorer. Apply the svg4everybody polyfill if IE support is required.

View polyfill on GitHub →