SVG-Icon-Sprites im Hyvä-Theme sauber organisieren

1. Warum SVG-Icon-Sprites die richtige Wahl im Hyvä-Theme sind

In den meisten Hyvä-Projekten wächst die Anzahl der phtml-Templates schnell, und mit ihr die Anzahl der Stellen, an denen ein einzelnes Icon als vollständiges Inline-SVG wiederholt wird. Eine Produktliste mit 24 Artikeln, die je ein Warenkorb-Icon und ein Herz-Icon enthält, schreibt denselben Pfad-Code fast 50 Mal in den DOM, nur mit unterschiedlichen CSS-Klassen. SVG-Icon-Sprites lösen genau dieses Problem: Die eigentliche Formdefinition existiert nur einmal in einer zentralen Sprite-Datei, jede Verwendungsstelle referenziert sie über eine ID. Das reduziert die HTML-Antwortgröße messbar, besonders auf Kategorieseiten und in Produktlisten mit vielen wiederkehrenden Icons.

Für ein Hyvä-Theme sind SVG-Icon-Sprites außerdem der konsequente nächste Schritt der bestehenden Philosophie: kein jQuery, kein zusätzliches JavaScript, keine Build-Abhängigkeit zur Laufzeit. Ein Icon-Sprite ist eine statische SVG-Datei, die der Browser nativ versteht, ohne Polyfill und ohne Runtime-Overhead. Damit passt das Sprite-Pattern besser zu Hyvä als etwa ein Icon-Font, der zusätzliche Requests, FOUC-Risiken und Lizenzfragen mit sich bringt. Die folgenden Abschnitte zeigen, wie sich SVG-Icon-Sprites in einem bestehenden Hyvä-Theme sauber aufbauen, generieren und pflegen lassen.

2. use xlink:href statt Inline-SVG in jedem phtml

Das technische Fundament von SVG-Icon-Sprites ist das <use>-Element mit einem xlink:href-Verweis auf eine Symbol-ID. Statt in jedem phtml-Template das komplette <path>-Markup zu wiederholen, referenziert das Template nur noch <svg><use xlink:href="#icon-cart"></use></svg>. Der Browser löst die Referenz gegen die im Dokument oder per externem Sprite geladene <symbol>-Definition auf und rendert das Icon exakt so, als stünde der vollständige Pfad direkt an dieser Stelle. Für gleiche Icons mit unterschiedlicher Größe genügt eine andere CSS-Klasse auf dem äußeren <svg>-Element.

Wichtig ist die korrekte Einbindung des Sprites selbst: Entweder wird die Sprite-Datei einmal inline in die Seite injiziert, etwa über ein Layout-Handle im Header, oder sie wird per externer Datei mit vollem Pfad referenziert. Ältere Safari-Versionen und einige Sicherheitsrichtlinien verlangen bei externen Sprites den vollständigen Pfad statt eines reinen Fragment-Identifiers. In einem Hyvä-Theme mit striktem CSP ist die Inline-Variante meist die robustere Wahl, weil sie keine zusätzliche Netzwerkanfrage erzeugt und mit der bestehenden CSP-Konfiguration ohne Sonderregeln funktioniert.

<!-- BAD: full inline SVG repeated in every phtml partial that shows this icon -->
<svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
        d="M3 3h2l.4 2M7 13h10l4-8H5.4M7 13L5.4 5M7 13l-2.293 2.293c-.63.63-.184 1.707.707 1.707H17" />
</svg>

<!-- GOOD: reference by id, the shape itself lives only once in the sprite -->
<svg class="w-5 h-5" aria-hidden="true">
  <use xlink:href="#icon-cart"></use>
</svg>

3. Hyvä-Core-Icon-Partials verstehen und erweitern

Der Hyvä-Kern liefert Icons standardmäßig nicht als Sprite, sondern über ViewModels wie Hyva\Theme\ViewModel\HeroiconsOutline und HeroiconsSolid, deren Methoden bei jedem Aufruf das vollständige SVG-Markup neu inline ausgeben. Das ist im Kern dasselbe Problem, das SVG-Icon-Sprites lösen sollen: Ruft ein Template $heroicons->cartOutline() zwanzig Mal auf einer Seite auf, erscheint der komplette Pfad-Code zwanzig Mal im gerenderten HTML. Für einzelne, selten wiederholte Icons ist das unproblematisch, für häufig wiederkehrende UI-Elemente wie Stern-Bewertungen, Mengen-Plus-Minus-Icons oder Warenkorb-Symbole in Listen summiert sich das schnell.

Eigene Icons lassen sich ergänzen, ohne die Core-ViewModels zu verändern: Ein eigenes Modul oder das Theme selbst legt zusätzliche SVG-Quellen in einem eigenen Ordner ab, etwa design/icons/source, und speist sie über den unten beschriebenen Build-Schritt in ein eigenes Sprite ein. Die Core-Icons können parallel weiterverwendet werden, für neue oder projektspezifische Icons entsteht so ein zweites, schlankes Sprite, das gezielt dort eingebunden wird, wo es gebraucht wird. Wichtig ist, in beiden Systemen dieselbe Namenskonvention für Icon-IDs zu verwenden, damit Entwickler nicht zwischen zwei Denkmodellen wechseln müssen.

4. Sprite-Generierung mit einem Node/npm-Build-Schritt

Die Sprite-Datei von Hand zu pflegen ist fehleranfällig, sobald mehr als eine Handvoll Icons im Projekt existieren. Ein kleines Node-Skript, das auf dem npm-Paket svg-sprite aufbaut, übernimmt diese Aufgabe zuverlässig: Es liest alle optimierten SVG-Dateien aus einem Quellordner, vergibt jeder Datei eine Icon-ID nach Dateinamen und schreibt eine einzige sprite.svg mit einem <symbol>-Element pro Icon. Der Build-Schritt lässt sich als npm-Script in package.json registrieren und in die bestehende Deploy-Pipeline neben dem Tailwind-Build einreihen, ohne zusätzliche Infrastruktur.

Für Hyvä-Projekte bietet es sich an, das generierte Sprite direkt im Theme-Ordner unter web/icons/ abzulegen, sodass Magentos Static-Content-Deploy die Datei automatisch mit ausliefert. Der Node-Build läuft dabei außerhalb des Magento-Prozesses, typischerweise als eigener npm-Befehl vor setup:static-content:deploy. Das folgende Beispiel zeigt ein vollständiges Build-Skript inklusive automatischer Versionierung über einen Zeitstempel im Dateinamen, was im Abschnitt zu Cache-Busting weiter unten aufgegriffen wird.

{
  "scripts": {
    "icons:optimize": "svgo -f design/icons/source -o design/icons/optimized",
    "icons:sprite": "node bin/build-icon-sprite.js",
    "icons:build": "npm run icons:optimize && npm run icons:sprite"
  },
  "devDependencies": {
    "svgo": "^3.2.0",
    "svg-sprite": "^2.0.4"
  }
}

// bin/build-icon-sprite.js
// Merges optimized SVG source files into one Hyva-compatible sprite file
const path = require('path');
const fs = require('fs');
const SVGSpriter = require('svg-sprite');

const spriter = new SVGSpriter({
  mode: {
    symbol: {
      dest: '.',
      sprite: 'sprite.svg',
    },
  },
  shape: {
    id: {
      generator: (name) => `icon-${path.basename(name, '.svg')}`,
    },
  },
});

const sourceDir = path.resolve(__dirname, '../design/icons/optimized');
fs.readdirSync(sourceDir)
  .filter((file) => file.endsWith('.svg'))
  .forEach((file) => {
    const filePath = path.join(sourceDir, file);
    spriter.add(filePath, null, fs.readFileSync(filePath, 'utf-8'));
  });

spriter.compile((error, result) => {
  if (error) {
    throw error;
  }

  const spriteSvg = result.symbol.sprite.contents;
  const version = Date.now();
  const outDir = path.resolve(
    __dirname,
    '../app/design/frontend/Mironsoft/default/Magento_Theme/web/icons'
  );

  fs.mkdirSync(outDir, { recursive: true });
  fs.writeFileSync(path.join(outDir, `sprite.${version}.svg`), spriteSvg);
  fs.writeFileSync(
    path.join(outDir, 'sprite-version.json'),
    JSON.stringify({ version })
  );

  console.log(`Sprite built: sprite.${version}.svg`);
});

5. SVGO-Optimierung vor der Sprite-Erstellung

Bevor einzelne SVG-Dateien in ein Sprite wandern, sollten sie durch SVGO optimiert werden. Design-Export-Tools wie Figma oder Illustrator schreiben regelmäßig überflüssige Metadaten, Editor-spezifische Namespaces, doppelte Gruppen und feste width/height-Attribute in die Datei, die im Sprite-Kontext nur Ballast sind. SVGO entfernt diese Elemente automatisch und normalisiert das viewBox-Attribut, sodass jedes Icon unabhängig von seiner Ursprungsgröße korrekt skaliert, sobald es per <use> referenziert wird.

Besonders wichtig für SVG-Icons im Hyvä-Theme ist, feste fill-Werte durch currentColor zu ersetzen, damit Icons die Textfarbe des umgebenden Elements übernehmen und sich per Tailwind-Klasse einfärben lassen, statt eine feste Farbe aus dem Export mitzuschleppen. Ein zentrales svgo.config.js im Projekt legt fest, welche Plugins aktiv sind, und verhindert, dass jeder Entwickler individuell optimierte Dateien mit abweichenden Ergebnissen einreicht. Der Optimierungsschritt läuft immer vor der Sprite-Generierung, nie danach, weil SVGO auf einzelnen Dateien arbeitet und die kombinierte Sprite-Datei nicht sauber verarbeiten kann.

# Optimize every source icon before the sprite build runs
npx svgo \
  --folder design/icons/source \
  --output design/icons/optimized \
  --config svgo.config.js

# svgo.config.js enables these plugins:
# - removeDimensions   (drop width/height, keep viewBox)
# - removeMetadata     (strip editor-generated metadata)
# - removeComments     (strip source comments)
# - convertColors      (currentColor for fill/stroke where safe)

6. Barrierefreiheit: aria-hidden, title und role=img

SVG-Icon-Sprites bringen keine automatische Barrierefreiheit mit, sie erfordern bewusste Entscheidungen pro Verwendungsstelle. Rein dekorative Icons, etwa ein Pfeil-Symbol neben einem bereits beschrifteten Link, sollten aria-hidden="true" erhalten, damit Screenreader sie überspringen und keine doppelte oder verwirrende Ansage entsteht. Trägt das Icon dagegen die einzige Information, etwa ein reiner Icon-Button ohne sichtbaren Text, braucht es role="img" zusammen mit einem <title>-Element, das den Zweck in Worten beschreibt.

Für interaktive Icons wie einen Schließen-Button oder ein Wunschzettel-Icon in einem <button>-Element reicht oft ein aria-label auf dem Button selbst, während das SVG darin weiterhin aria-hidden="true" bekommt, da die Beschriftung bereits auf Elternebene existiert. Fokus-Management betrifft vor allem Icons in eigenständigen interaktiven Elementen: Ein <svg> ohne tabindex ist selbst nicht fokussierbar, was korrekt ist, solange es in einem fokussierbaren Elternelement wie einem Button oder Link liegt. Wird das SVG versehentlich direkt interaktiv gemacht, entstehen doppelte Tab-Stopps, die Screenreader-Nutzer verwirren.

7. Ein wiederverwendbares Icon-phtml-Partial bauen

Damit Entwickler im Team nicht bei jedem Icon erneut über aria-hidden, Größe und Sprite-Pfad nachdenken müssen, lohnt sich ein zentrales Icon-Partial, das Name, Größe und optionalen Titel als Parameter entgegennimmt. Das Partial kapselt die komplette Logik zur Barrierefreiheit: Ist ein Titel gesetzt, wird automatisch role="img" und ein <title>-Element erzeugt, fehlt er, greift aria-hidden="true". Andere Templates rufen das Partial über $block->getLayout()->createBlock(...)->setData(...)->toHtml() oder direkter über eine ViewModel-Methode auf.

Ein solches Partial reduziert Redundanz auf Template-Ebene erheblich und sorgt für konsistente Icon-Größen im gesamten Theme, weil Größenangaben über eine begrenzte Menge zulässiger Werte statt frei getippter Tailwind-Klassen erfolgen. Änderungen an der Barrierefreiheits-Logik, etwa eine neue Anforderung an aria-describedby, müssen dann nur an einer Stelle gepflegt werden, statt in Dutzenden einzelnen phtml-Dateien gesucht zu werden.

<?php
/** @var \Magento\Framework\View\Element\Template $block */
$iconName = $block->getData('icon_name') ?: 'cart';
$size = $block->getData('icon_size') ?: '5';
$title = $block->getData('icon_title');
?>
<svg class="w-<?= $block->escapeHtmlAttr($size) ?> h-<?= $block->escapeHtmlAttr($size) ?>"
     <?= $title ? 'role="img"' : 'aria-hidden="true"' ?>>
  <?php if ($title): ?>
    <title><?= $block->escapeHtml($title) ?></title>
  <?php endif; ?>
  <use xlink:href="#icon-<?= $block->escapeHtmlAttr($iconName) ?>"></use>
</svg>

8. Cache-Busting und Versionierung der Sprite-Datei

Eine zentrale Sprite-Datei, die von jeder Seite referenziert wird, profitiert maximal vom Browser-Cache, birgt aber ein Risiko: Ändert sich ein Icon oder kommt ein neues hinzu, darf der Browser nicht die alte, bereits gecachte Version weiterverwenden. Der Node-Build-Schritt aus Abschnitt vier löst das, indem er bei jedem Lauf einen Zeitstempel in den Dateinamen schreibt, etwa sprite.1721732400.svg. Referenzierende Templates lesen den aktuellen Dateinamen aus einer kleinen Metadatei oder einer Konfigurationsvariable, statt ihn hart zu kodieren.

Für Magento-Deployments bietet es sich an, den aktuellen Sprite-Dateinamen in einer JSON-Datei im Theme abzulegen, die ein ViewModel zur Laufzeit einliest und in den Pfad einsetzt, wenn das Sprite als externe Datei eingebunden wird. Wird das Sprite stattdessen inline in den Seiten-Header injiziert, entfällt das Cache-Busting-Problem für die Sprite-Datei selbst komplett, weil sie Teil des HTML-Dokuments wird und mit dessen eigener Cache-Strategie ausgeliefert wird. Diese Variante ist bei kleineren bis mittleren Icon-Sets meist die pragmatischere Lösung für SVG-Icon-Sprites im Theme.

9. SVG-Icon-Sprites im Vergleich zu Icon-Fonts aus der Luma-Welt

Luma-Themes lösten Icons traditionell über Icon-Fonts: eine einzelne Font-Datei mit Icons als Glyphen, eingebunden über @font-face und angesprochen über CSS-Pseudoelemente wie ::before. Dieses Muster bringt mehrere strukturelle Nachteile mit, die in einem modernen Hyvä-Theme unnötig sind. Eine Font-Datei muss vollständig geladen werden, bevor auch nur ein Icon sichtbar ist, was auf langsamen Verbindungen zu einem kurzen Flash of Unstyled Content führt, bei dem Icons zunächst als Kästchen oder gar nicht erscheinen.

SVG-Icon-Sprites vermeiden dieses Problem vollständig, weil sie kein separates Font-Format benötigen und als reguläres Markup direkt mit der Seite ausgeliefert werden. Zusätzlich lassen sich einzelne Icon-Farben, Größen und sogar Animationen pro Icon steuern, was bei Icon-Fonts nur eingeschränkt über Farbe und Größe möglich ist, niemals aber über Formänderungen. Die folgende Tabelle stellt die drei Ansätze direkt gegenüber.

In der Praxis zeigt sich der Unterschied vor allem bei Seiten mit vielen wiederholten Icons: Ein Sprite lädt einmal und wird für jede weitere Verwendung aus dem Cache referenziert, während Inline-SVG pro phtml die Antwortgröße bei jeder Wiederholung erneut aufbläht und ein Icon-Font selbst bei nur drei benötigten Icons oft mehrere Dutzend ungenutzte Glyphen mitschleppt. Für neue Hyvä-Projekte gibt es kaum noch einen Grund, auf das Sprite-Pattern zu verzichten.

10. Zusammenfassung

SVG-Icon-Sprites lösen ein Problem, das in vielen Hyvä-Themes unbemerkt wächst: wiederholtes Inline-SVG-Markup, das die Seitengröße unnötig erhöht und Änderungen am Icon-Set erschwert. Das <use xlink:href>-Pattern ersetzt redundanten Pfad-Code durch eine einfache Referenz auf eine zentrale Sprite-Datei. Ein Node-Build-Schritt mit svg-sprite, kombiniert mit SVGO-Optimierung im Vorfeld, automatisiert die Pflege dieser Sprite-Datei zuverlässig und ohne manuellen Aufwand bei jedem neuen Icon.

Barrierefreiheit ist bei SVG-Icon-Sprites kein Nebeneffekt, sondern eine bewusste Entscheidung pro Icon: aria-hidden="true" für dekorative Elemente, role="img" mit <title> für bedeutungstragende Icons. Ein wiederverwendbares Icon-Partial kapselt diese Logik an einer Stelle, Cache-Busting über versionierte Dateinamen stellt sicher, dass Änderungen zuverlässig beim Nutzer ankommen. Im Vergleich zu Icon-Fonts aus der Luma-Welt spart das Sprite-Pattern Requests, vermeidet FOUC und passt ohne zusätzliches JavaScript in die bestehende Hyvä-Architektur.

11. FAQ: SVG-Icon-Sprites im Hyvä-Theme