1. SVG sprites with <use>: the scalable solution

How it works

<svg>
  <symbol id="icon-search" viewBox="0 0 24 24">
    <path d="..." />
  </symbol>
  <symbol id="icon-user" viewBox="0 0 24 24">
    <path d="..." />
  </symbol>
</svg>

We have a large SVG container in which multiple icons are defined as <symbol> elements. Each symbol has:

• a unique ID (icon-search, icon-user)
• a viewBox value (0 0 24 24) — the icon’s coordinate system
• the path (<path d="...">) — the actual icon shape

Although SVG sprites can also be grouped using <g> elements, <symbol> provides decisive advantages. A <g> only groups SVG elements and can therefore be used as a template for an icon. However, it has no own viewBox, meaning all icons share the parent SVG coordinate system. This makes differing sizes and proportions harder to manage. <symbol>, on the other hand, is designed specifically for reusable SVG content: each symbol can define its own viewBox and is not rendered directly by default. Therefore, <symbol> is usually the better choice for modern SVG sprites, while <g> is more suitable for simple grouping inside a graphic.

Usage:

<svg class="icon">
  <use href="#icon-search"></use>
</svg>

The browser renders the icon here, while the definition remains centralized.

Advantages

• Performance:
  Each icon is defined only once.
• Maintainability:
  Changes apply everywhere automatically.
• Extensibility:
  New icons are added as additional <symbol> elements.
• Scalability:
  Proven solution for large design systems.

The downsides

SVG sprites come with certain trade-offs. A build step is usually required, as the sprite file is typically generated automatically rather than written manually. This slightly increases setup complexity. Another limitation concerns styling. While inline SVG allows individual paths to be targeted and animated via CSS, this is not possible with sprites using <use>. Additionally, there is architectural dependency: if the sprite is served from an external server or CDN, it may be restricted or blocked by Content Security Policies (CSP) or specific deployment configurations.

2. Inline SVG: The Flexible Solution

How it works

<svg viewBox="0 0 24 24">
  <path d="M10 18a8 8 0 1 1 5.293-14.293..." />
</svg>

We embed the SVG directly into our HTML. The browser renders it immediately. There is no font or external file involved.

Advantages

Inline SVG provides maximum flexibility. Individual paths can be styled and animated directly via CSS:

svg path {
  fill: currentColor;
}

The icon automatically inherits the text color.

Accessibility works smoothly:

<button aria-label="Search">
  <svg aria-hidden="true">
    <path d="..." />
  </svg>
</button>

Multi-color icons are no problem. CSS animations also work.

Downsides of inline SVG

• DOM growth with many icons.
• Duplication of identical SVG code.
• Inconsistencies without a central design system.

Accessibility considerations

A common mistake is to blindly apply aria-hidden="true" to all icons. While practical at first glance, this hides meaningful icons from screen readers. A warning icon next to a form field, for example, conveys important information. If it is hidden, that meaning is lost for assistive technologies.

The correct approach depends on context. An arrow next to a “read more” link is decorative and can be hidden. An icon that communicates status or information must be accessible to assistive technologies.

Icons serve different purposes, and a well-designed SVG strategy must reflect that. A blanket aria-hidden="true" for all icons is therefore incorrect. The key question is whether an icon is purely decorative or carries meaningful information.

3. CSS masks

How it works

<span class="icon-search"></span>

.icon-search {
  width: 1rem;
  height: 1rem;
  background-color: currentColor;
  mask: url(search.svg) no-repeat center;
  mask-size: contain;
  -webkit-mask: url(search.svg) no-repeat center;
  -webkit-mask-size: contain;
}

The mask property uses the SVG as a shape mask. Only the areas allowed by the SVG become visible.

Advantages

• Very simple HTML.
• Good CSS maintainability in 2026.
• No additional nodes in the DOM, as with inline SVGs

Limitations

CSS masks only support single-color icons. Multi-color icons or gradients are not possible. With `mask-image`, you have to manipulate the `background-color`—and that only works if the area behind it is visible. CSS errors are also hard to spot—
What's wrong, the mask? The image? The rendering.

4. Internationalization and Translation

Icons do not require translation. A search icon is universally understood as a magnifying glass.

However, the icon itself has no intrinsic meaning. Its meaning comes from the UI context. The button label (aria-label="Search") must be translated — the icon remains unchanged.

Translation always happens outside the icon:

<button aria-label="Search">
  <svg class="icon" aria-hidden="true">
    <use href="#icon-search"></use>
  </svg>
</button>

Here, the aria-label is translated. The icon stays the same.

The anti-pattern: <title> in SVG

SVG icons can be made accessible using a <title> element, which provides a textual description inside the SVG.

<svg role="img">
  <title>Search</title>
  <path d="..." />
</svg>

Embedding meaning inside the SVG couples the asset to UI semantics. The same icon may have different meanings depending on context. It is better to treat icons as meaning-agnostic visual resources and define accessibility in the UI layer.

<svg aria-hidden="true">
  <use href="#icon-search"></use>
</svg>

aria-hidden="true" tells assistive technologies: the label comes from the surrounding element.

5. Accessibility Comparison

• Inline SVG: Very good. Supports role="img", <title>, and labels.
• SVG sprites: Very good. Same possibilities as inline SVG with central reuse.
• CSS masks: Moderate. The icon itself is semantically empty; labeling must come from the container.
• Icon fonts: Poor. Screen readers interpret text glyphs instead of graphics.

6. Performance Comparison

• Icon fonts: no DOM overload, but mapping complexity adds overhead.
• Inline SVG: many DOM nodes for the browser to manage.
• SVG sprites: best caching: one file, many icons.
• CSS masks: minimal DOM and good caching behavior.

For pure performance, SVG sprites win.

7. Maintainability and Extensibility

• Inline SVG: Very flexible, but leads to duplication.
• CSS masks: Simple and clean as long as single-color icons are sufficient.
• SVG sprites: Centralized management, no duplicates, stable IDs. Changes apply globally — the most sustainable long-term solution.

8. Real-world Design System Examples

So far, we’ve seen theoretical differences. Now let’s look at two real-world implementations. Both are in production. Both solve the icon problem differently. There is no single correct icon system — only the right system for a given context.

IBM Carbon: icons as UI components

The IBM Carbon Design System treats icons not as files, but as components.

Instead of:

<svg class="icon">
  <use href="#icon-search"></use>
</svg>

you write:

<Search size={16} />

This is a fundamental architectural shift. Icons become semantic UI building blocks.

1. Tight design system integration — icons are part of a controlled API.
2. Safety through structure — typing prevents misuse.
3. Accessibility by default — icons always exist in a UI context.

The “Kolibri” approach: lightweight instead of a design system

Kolibri takes the opposite approach. Icons remain simple assets.

Variant A: CSS mask images

.icon-search {
  width: 24px;
  height: 24px;
  mask-image: url('icons/search.svg');
  mask-size: contain;
  mask-repeat: no-repeat;
  background-color: currentColor;
}

<span class="icon-search"></span>

Variant B: lightweight SVG sprite

<svg class="icon">
  <use href="/icons.svg#search"></use>
</svg>

Typical characteristics

1. Minimal abstraction layer
2. Performance and cache friendliness
3. Low entry barrier

9. Final solution: pure HTML SVG icon system

For many HTML/CSS projects, a simple SVG sprite system is fully sufficient.

Central SVG sprite file

<svg xmlns="http://www.w3.org/2000/svg">
  <symbol id="icon-search" viewBox="0 0 24 24">
    <path d="M10 18a8 8 0 1 1 5.293-14.293A8 8 0 0 1 10 18zm11 3-6-6"/>
  </symbol>
</svg>

This is the central icon registry. Each icon exists exactly once.

CSS styling

.icon {
  width: 1em;
  height: 1em;
  display: inline-block;
  vertical-align: middle;
  fill: currentColor;
}

The key part:

fill: currentColor;

The icon automatically inherits its text color.

Dark mode

@media (prefers-color-scheme: dark) {
  :root {
    --icon-color: #f2f2f2;
  }
}

Usage

<svg class="icon">
  <use href="#icon-search"></use>
</svg>

10. Automated SVG System

Manual sprite files work well, but automation is useful for larger projects.

Folder structure

icons/
  search.svg
  user.svg
  check.svg
  bell.svg

dist/
  sprite.svg

src/
  icon.css

scripts/
  build-icons.js

index.html

Build script

import fs from "fs";
import path from "path";

const ICON_DIR = "./icons";
const OUTPUT = "./dist/sprite.svg";

function buildSprite() {
  const files = fs.readdirSync(ICON_DIR)
    .filter(f => f.endsWith(".svg"));

  const symbols = files.map(file => {
    const name = path.basename(file, ".svg");
    const svg = fs.readFileSync(path.join(ICON_DIR, file), "utf8");

    const content = svg
      .replace(/<svg[^>]*>/, "")
      .replace("</svg>", "");

    return `
      <symbol id="icon-${name}">
        ${content}
      </symbol>
    `;
  });

  const sprite = `
    <svg xmlns="http://www.w3.org/2000/svg">
      ${symbols.join("")}
    </svg>
  `;

  fs.writeFileSync(OUTPUT, sprite);

  console.log(`Sprite built: ${OUTPUT}`);
}

buildSprite();

node scripts/build-icons.js

Architecture overview

Source icons (SVG files)
        ↓
Linting
        ↓
Build script
        ↓
Sprite (dist/sprite.svg)
        ↓
HTML usage with <use>
        ↓
CSS styling & sizing
        ↓
Browser renders icons