Icon

Icons are inline SVG elements wrapped in a container class. They inherit colour from the surrounding text, maintain a fixed square aspect ratio, and are accessible by default.

Principles

• Inline SVG only: never use <img> tags for icons. Inline SVGs allow colour inheritance and eliminate extra HTTP requests.
• currentColor always: all icon <path> elements must use fill="currentColor" so the icon inherits the parent's text colour. This keeps icons visually consistent across themes and contexts.
• No xmlns: strip xmlns and xmlns:xlink attributes from inline SVGs. They are only needed for standalone .svg files, not inline usage.
• Square aspect ratio: icons are always 1:1. Use viewBox to define the coordinate system, not width/height.
• Brand icons only: do not use Material Design, Font Awesome, Heroicons, Feather, or any other third-party icon source. Use the brand icons from assets/images/svg-icons/. If no icon exists for your need, request one from the design team.

Icon Wrapper

Use .svg-icn to wrap inline SVG icons. This class constrains the icon to a fixed size and enforces the square aspect ratio.

<div class="svg-icn" data-icon="arrow-right">
  <svg width="100%" height="100%" viewBox="0 0 24 24" fill="none">
    <path d="M5 12h14M12 5l7 7-7 7" fill="currentColor"/>
  </svg>
</div>

Properties

data-icon attribute

Always include a data-icon attribute with a descriptive name. This makes icons identifiable in code. Raw SVG paths are unreadable without it.

<div class="svg-icn" data-icon="chevron-down">...</div>
<div class="svg-icn" data-icon="close">...</div>
<div class="svg-icn" data-icon="search">...</div>

Use lowercase kebab-case for icon names (e.g. arrow-right, chevron-down, arrow-top-right).

Logos

Logos follow the same data-attribute pattern as icons, using data-logo instead of data-icon. The wrapper uses a generic .svg-logo class, and the logo name goes on the <svg> element.

<div class="svg-logo" style="aspect-ratio: 1050 / 505">
  <svg data-logo="by-default-centered" viewBox="0 0 1050 505" width="100%" height="100%" fill="none" aria-hidden="true">
    <path d="..." fill="currentColor"/>
  </svg>
</div>

Key differences from icons

CSS targeting

Use :has() to target the wrapper based on a specific logo:

.svg-logo:has([data-logo="by-default-centered"]) {
  width: var(--sidebar-logo-width);
}

SVG Cleaner workflow

node assets/js/svg-clean.js --logo --logo-name brand-name --current-color --strip-comments

This outputs a <div class="svg-logo"> wrapper with data-logo="brand-name" on the <svg> element.

Icon in Buttons

For icon-only buttons, add the data-icon-only attribute and .svg-icn as the SVG wrapper. Always include aria-label.

<button class="button" data-icon-only aria-label="Close">
  <div class="svg-icn">
    <svg width="100%" height="100%" viewBox="0 0 24 24" fill="none">
      <path d="M18 6L6 18M6 6l12 12" fill="currentColor"/>
    </svg>
  </div>
</button>

See the Button documentation for full button modifier details.

SVG Requirements

Every icon SVG must follow these rules before being added to the codebase:

Standard viewBox

Use 0 0 24 24 as the default icon grid. If an icon uses a different coordinate system, preserve its original viewBox. Do not rescale manually.

Icon Sprite

Products consuming the system as a package receive the whole registry as one file: icons.svg, a <symbol> sprite built from every icon in assets/images/svg-icons/. It ships alongside design-system.css in the design-system-dist artefact repo.

Symbol ids are the lowercase kebab-case icon names from the registry below — arrow-right, sidebar-left-open, and so on. Reference a symbol with <use> inside the standard wrapper:

<div class="svg-icn" data-icon="arrow-right">
  <svg fill="none" width="100%" height="100%" aria-hidden="true">
    <use href="/assets/icons/icons.svg#arrow-right"></use>
  </svg>
</div>

Two rules carry over unchanged: the .svg-icn wrapper still controls sizing, and icons still inherit colour through currentColor. One new constraint: <use href> does not load cross-origin, so serve the sprite from your own domain — copy it into your project rather than hotlinking it.

Inside this repo, icons stay inline (the docs pages inline each SVG directly); the sprite is the delivery format for package consumers.

Accessibility

• Decorative icons: add aria-hidden="true" to the SVG when the icon is purely visual and accompanied by text.
• Meaningful icons: add aria-label to the parent element (e.g. the button) when the icon conveys meaning without visible text.
• Icon buttons: always include aria-label on the <button> element.

<!-- Decorative: icon next to text -->
<div class="svg-icn" data-icon="check">
  <svg width="100%" height="100%" viewBox="0 0 24 24" fill="none" aria-hidden="true">
    <path d="M20 6L9 17l-5-5" fill="currentColor"/>
  </svg>
</div>

<!-- Meaningful: icon button with no visible text -->
<button class="button is-icon" aria-label="Close menu">
  <div class="svg-icn">
    <svg width="100%" height="100%" viewBox="0 0 24 24" fill="none" aria-hidden="true">
      <path d="M18 6L6 18M6 6l12 12" fill="currentColor"/>
    </svg>
  </div>
</button>

Colour

Icons inherit colour through currentColor. To change an icon's colour, change the text colour of its parent. Never hardcode a fill value.

<!-- Icon inherits the faded text colour -->
<div class="text-faded">
  <div class="svg-icn" data-icon="info">
    <svg width="100%" height="100%" viewBox="0 0 24 24" fill="none" aria-hidden="true">
      <path d="M12 2a10 10 0 100 20 10 10 0 000-20zm1 15h-2v-6h2v6zm0-8h-2V7h2v2z" fill="currentColor"/>
    </svg>
  </div>
</div>

Icon Shorthand

Use {{icon:name}} in any markdown file processed by the doc generator to render an inline icon. The shorthand is expanded at build time. The actual SVG is read from assets/images/svg-icons/ and injected as a standard .svg-icn wrapper.

{{icon:check}}         → renders the check icon
{{icon:arrow-right}}   → renders the arrow-right icon
{{icon:t-shirt}}       → renders the t-shirt icon

The name must match a key from the icon registry below. If the name is not found, a warning is logged during generation and an HTML comment is output instead.

This shorthand only works in files processed by cms/generator/generate-docs.js. It does not work in standalone HTML pages.

A second placeholder renders the whole set at once: put {{icon-registry}} on a line of its own and the generator expands it into the full registry table. The Registry section below is built this way.

SVG Cleaner Tool

Use the SVG Cleaner to prepare icons before adding them to the codebase. The tool automates the required cleanup:

• Strips xmlns attributes
• Sets fills to currentColor (when enabled)
• Wraps in .svg-icn with data-icon attribute (when "Icon" is checked)
• Strips XML comments
• Optional minification

For CLI usage:

echo '<svg>...</svg>' | node assets/js/svg-clean.js --current-color --icon --icon-name arrow-right --strip-comments

Naming Conventions

Rules

Registry

The full brand icon set. This table is generated at build time from assets/images/svg-icons/, so it always matches the source directory. The data-icon value is the name to use with the wrapper, the shorthand, and the sprite. For a categorised view with copy and download, see the Brand Book iconography page.

Requesting a New Icon

If you need an icon that is not in the brand icon set:

1. Check the brand book: the icon you need may exist under a different name. See the Visual Identity page for the full icon grid.
2. Document the request: describe the concept, intended size, and where it will be used
3. Submit to the design team: new icons must match the existing style (24x24 grid, single-colour, rounded corners)
4. Do not use a placeholder: wait for the brand icon to be designed rather than shipping with a generic substitute

Maintaining a consistent icon language across the site is more important than shipping fast with mismatched icons.