Foundations

Iconography

Font Awesome supplies every icon in the product. Twenty-nine are wrapped as named Figma components for the actions that recur across the suite; anything else in the library is available but unnamed.

Figma source: Icons ↗

Where icons come from

Icons are Font Awesome glyphs, set as text at 14px in the Icon text style. They inherit colour from the semantic --icon-* tokens rather than carrying their own.

Token	Resolves to	Use for
`--icon-primary`	brand blue	Interactive icons — the default.
`--icon-accent-1`	`blue/200`	Decorative accents. Not for anything that must be read.
`--icon-accent-2`	white	Icons on a dark or brand-filled surface.
`--icon-accent-3`	black	Icons that read as text, e.g. inside a table cell.
`--icon-accent-4`	`gray/500`	Secondary and supporting icons: input affordances, dismiss controls.

Named icon components

These wrap a specific glyph so the intent is fixed across products. Use the named component rather than picking the glyph yourself — it is what keeps “close” meaning the same shape everywhere.

Component	Font Awesome glyph	Meaning
Save	`save`	Commit changes
Close	`times`	Dismiss a dialog, remove a pill
Trash	`trash`	Delete permanently
PDF	`file-pdf`	Export or download as PDF
Add	`plus`	Create a new record or row
Confirm	`check`	Success, completion, selected
Edit	`pencil`	Enter edit mode
Search	`search`	Search or filter
Menu Down / Up / Side	`caret-down` / `caret-up` / `caret-right`	Menu affordance — a menu will open
Expand Down / Up / Right	`chevron-down` / `chevron-up` / `chevron-right`	Disclosure — content expands in place

Caret and chevron are not interchangeable

The file distinguishes them deliberately: a caret opens a menu that floats above the page, a chevron expands content inline. Users learn the difference without being told, and swapping them makes both meaningless.

Accessible icons

Whether an icon needs a name depends entirely on whether it carries meaning on its own.

Decorative vs meaningful

html

<!-- Icon beside a visible label: hide it from assistive tech -->
<button class="cds-button cds-button--secondary">
  <span aria-hidden="true" class="fa fa-plus"></span> Add attachment
</button>

<!-- Icon alone: the button needs an accessible name -->
<button class="cds-button cds-button--secondary cds-button--icon-only" aria-label="Delete row">
  <span aria-hidden="true" class="fa fa-trash"></span>
</button>

When to use it

Add aria-hidden="true" to an icon that sits beside a visible text label — otherwise it is announced twice.
Give every icon-only control an aria-label naming the action, not the picture: “Delete row”, not “trash icon”.
Keep icon-only controls to genuinely universal glyphs — close, search, add, edit.

When not to use it

Do not rely on an icon alone to convey a state that has no text equivalent.
Do not label an icon with its shape. “Caret” tells a screen-reader user nothing about what will happen.
Do not use --icon-accent-1 for a meaningful icon — blue/200 measures 2.80:1 on white and fails non-text contrast.