Encadrés d’alerte avec icônes : SVG inline + variables CSS (sans polices d’icônes)

Pourquoi arrêter d’utiliser des polices d’icônes

Les polices d’icônes étaient une astuce intelligente à l’époque où nous luttions contre des navigateurs anciens et où les outils SVG étaient médiocres. Elles « fonctionnent » encore jusqu’à ce que vous ajoutiez des contraintes réelles : politique de sécurité de contenu, protections de confidentialité, intégrité des sous-ressources, bizarreries de chargement de polices et exigences d’accessibilité qui ne s’arrêtent pas à « ça s’affiche sur ma machine ».

Les polices d’icônes échouent de façons qui ressemblent à des « bugs UI aléatoires »

FOIT/FOUT n’est pas qu’un problème marketing. Quand la police ne se charge pas, les icônes peuvent s’afficher comme tofu (carrés de glyphe manquants), des caractères de la zone d’usage privé, ou le mauvais glyphe à cause de la police de secours choisie. Ce n’est pas seulement moche ; c’est trompeur. Un encadré « danger » sans icône peut être acceptable. Un encadré avec la mauvaise icône, c’est comment on fait en sorte que quelqu’un supprime le mauvais jeu de données.

Le sous-ensemble de polices est un champ miné. Quelqu’un essaie d’optimiser le poids en ne gardant que les glyphes utilisés. Puis une nouvelle page utilise une icône absente du sous-ensemble. En staging tout a l’air correct (police complète mise en cache), en prod ça ne l’est pas. Bienvenue dans le bug qui vous fait perdre un après-midi et quelques relations.

Accessibilité avec les polices d’icônes, c’est surtout de l’espoir. Les lecteurs d’écran n’interprètent pas « glyphe au point de code E018 » comme « avertissement ». On finit par parsemer du texte caché, et ça se désynchronise.

CSP et navigateurs d’entreprise : beaucoup d’organisations bloquent les polices provenant d’origines tierces, et certaines désactivent complètement les polices distantes. La police d’icônes est souvent la première chose qui saute. Le SVG inline, bien fait, peut être compatible CSP et autonome.

De plus : les polices d’icônes encouragent le style paresseux (on règle juste la font-size et on s’en contente). Le SVG vous force à gérer la taille, le viewBox et l’alignement. C’est pénible dix minutes, puis ça vous sauve pour des années.

Blague #1 : Les polices d’icônes sont comme un RAID 0 fait de sentiments : ultra-rapide jusqu’au moment où vous avez besoin que ce soit correct.

Faits et un peu d’histoire (utile, pas nostalgique)

• Fait 1 : Les polices d’icônes sont devenues populaires parce que les outils web et le support navigateur rendaient le SVG gênant, tandis que les polices étaient déjà mises en cache et compressibles.
• Fait 2 : Beaucoup de polices d’icônes utilisent la zone d’usage privé Unicode, qui est explicitement « votre problème » pour le sens et la compatibilité.
• Fait 3 : SVG 1.1 est devenu recommandation W3C en 2011 ; l’adoption massive a traîné car l’écosystème d’outils a mis du temps à mûrir.
• Fait 4 : Le passage des images raster vers le SVG inline s’est accéléré quand le design responsive a rendu les icônes raster à taille fixe pénibles.
• Fait 5 : Les propriétés personnalisées CSS (variables) ont été largement disponibles dans les navigateurs modernes vers 2017–2018, ce qui a rendu la thématisation plus simple sans préprocesseurs.
• Fait 6 : Les politiques CSP réelles se sont durcies après des incidents XSS médiatisés qui ont poussé les entreprises à restreindre scripts inline, polices distantes et sources non sûres.
• Fait 7 : L’arrivée de prefers-color-scheme a rendu les polices d’icônes moins pratiques car on veut souvent que traits/fonds suivent currentColor et des tokens de thème.
• Fait 8 : Les « sprites SVG » (<symbol>) ont répondu au problème de markup répétitif, mais ont introduit leurs propres considérations cross-origin et de cache.

Objectifs de conception : ce que signifient des encadrés « bons »

Les encadrés d’alerte ne sont pas décoratifs. Ils structurent l’attention. Dans des systèmes de production et des docs internes, les encadrés sont souvent la dernière garde avant qu’une action coûteuse ne soit entreprise. Le composant doit donc être :

Conseil d’opinion : traitez les encadrés comme les logs. Un peu de structure au départ évite beaucoup de chaos plus tard. Vous voulez un petit ensemble de types (info/warn/danger/success), un jeu d’icônes stable et des tokens pour accent/fond/bord. Le reste, c’est du chipotage.

Composant de référence : HTML + SVG inline + variables CSS

Ceci est une base adaptée à la production. Pas de step de build requis. Pas de dépendance à des bibliothèques d’icônes externes. Dégrade raisonnablement. Et trivial à thématiser.

Pattern de balisage (icône décorative)

La plupart des icônes d’encadré sont décoratives. Le type d’encadré est communiqué par le texte du titre (« Warning », « Note », « Danger »), pas par l’icône seule. Dans ce cas, cachez le SVG pour les technologies d’assistance avec aria-hidden="true".

cr0x@server:~$ cat callout-example.html
<aside class="callout callout--warning" role="note">
  <div class="callout__icon" aria-hidden="true">
    <svg viewBox="0 0 24 24" focusable="false">
      <path d="M12 9v4"></path>
      <path d="M12 17h.01"></path>
      <path d="M10.3 4.3 2.6 18a2 2 0 0 0 1.7 3h15.4a2 2 0 0 0 1.7-3L13.7 4.3a2 2 0 0 0-3.4 0z"></path>
    </svg>
  </div>

  <div>
    <p class="callout__title">Warning</p>
    <p class="callout__body">Do not run this migration twice. The second run will delete data you meant to keep.</p>
  </div>
</aside>

Pattern CSS (tokens d’abord, sélecteurs ensuite)

Remarquez comment le composant utilise currentColor dans le SVG et définit les couleurs via des propriétés personnalisées. Cela maintient la thématisation propre : vous définissez --accent et l’icône + la bordure suivent.

cr0x@server:~$ cat callout.css
.callout{
  --accent: #60a5fa;
  --c-bg: color-mix(in srgb, var(--accent) 16%, transparent);
  --c-border: color-mix(in srgb, var(--accent) 35%, #223047);

  display: grid;
  grid-template-columns: 22px 1fr;
  gap: 12px;
  padding: 14px;
  border-radius: 12px;

  background: var(--c-bg);
  border: 1px solid var(--c-border);
  align-items: start;
}

.callout__icon svg{
  width: 100%;
  height: 100%;
  display: block;
  stroke: currentColor;
  fill: none;
  stroke-width: 1.9;
  stroke-linecap: round;
  stroke-linejoin: round;
}

.callout--warning{ --accent: #fbbf24; }
.callout--danger{ --accent: #fb7185; }
.callout--success{ --accent: #34d399; }

Quand ne pas inline le SVG

Inliner du SVG partout peut alourdir le HTML si vous avez des centaines d’icônes sur une page. C’est un vrai compromis. Si vos pages de docs ont des dizaines d’encadrés, envisagez un sprite de symboles ou un step de build pour dédupliquer. Mais n’allez pas vers un sprite juste parce que ça semble « plus propre ». Choisissez-le quand vous avez mesuré la répétition et que cela affecte votre chemin critique.

Accessibilité : ce qui casse discrètement

La plupart des échecs d’accessibilité ne ressemblent pas à des échecs. Ils ressemblent à « ça marche pour moi ». Puis un audit arrive, ou un employé dépose une plainte, ou votre équipe produit est bloquée. Les encadrés sont des composants simples, ce qui rend d’autant plus embarrassant de les rater.

Icônes décoratives vs informatives

Décidez si l’icône transmet une information absente du texte. Si le titre dit déjà « Warning », l’icône est décorative. Utilisez aria-hidden="true" sur le conteneur de l’icône ou le SVG et évitez les annonces redondantes.

Si l’icône est le seul indicateur (déconseillé), elle doit avoir un nom accessible. Mieux : incluez toujours un titre visible.

Rôles et sémantique

Utilisez des conteneurs sémantiques. <aside> convient bien aux encadrés ; il signale un « contenu de support ». Pour les technologies d’assistance, role="note" est souvent raisonnable. Évitez le spam de rôles. Ne transformez pas chaque encadré en alert ; les utilisateurs s’en lasseront et les lecteurs d’écran l’annonceront de manière agressive.

Contraste des couleurs et thématisation

Votre couleur d’accent n’est pas votre couleur de bordure. Votre bordure n’est pas votre fond. Lie-les avec des variables, mais ne supposez pas qu’une seule valeur marche pour tous les thèmes. Si vous devez calculer des nuances, utilisez des méthodes sûres comme color-mix() avec pourcentages raisonnables et vérifiez le contraste en modes clair et sombre.

Comportement du focus et contenu interactif dans les encadrés

Les encadrés contiennent souvent des liens (« Voir le runbook »). Assurez-vous que les liens ont des styles de focus visibles et évitez de placer des contrôles interactifs trop près de l’icône si cela affecte les cibles tactiles sur mobile. Le conteneur d’encadré lui-même ne devrait pas être focusable sauf s’il est cliquable. Les encadrés cliquables sont généralement un piège UX : les gens essaient de sélectionner du texte et se font rediriger.

Thématisation avec variables CSS : mode sombre, couleurs de marque et overrides par conteneur

Les variables CSS sont le type de choix le plus ennuyeux et le meilleur. Elles sont configurables à l’exécution, se propagent naturellement et n’exigent pas de gymnastique de préprocesseur. Pour les encadrés, vous voulez un petit ensemble de tokens que vous pouvez surcharger à différents niveaux :

• Valeurs par défaut globales (:root)
• Overrides de thème (clair/sombre ou skins produit)
• Overrides au niveau du conteneur (site docs intégré dans un portail partenaire)
• Overrides au niveau composant (un encadré précis nécessite un accent personnalisé)

Stratégie de tokens qui scale

N’appliquez pas des couleurs brutes sur chaque type d’encadré dans dix fichiers différents. Définissez des tokens sémantiques pour les types et calculez des valeurs dérivées (fond, bordure) avec des règles prévisibles. Votre futur vous remerciera lors d’une refonte de marque sans chercher le fichier CSS perdu.

cr0x@server:~$ cat tokens.css
:root{
  --callout-radius: 12px;
  --callout-pad: 14px;
  --callout-gap: 12px;

  --callout-info: #60a5fa;
  --callout-warning: #fbbf24;
  --callout-danger: #fb7185;
  --callout-success: #34d399;

  --callout-mix-bg: 16%;
  --callout-mix-border: 35%;
}

.callout{
  border-radius: var(--callout-radius);
  padding: var(--callout-pad);
  gap: var(--callout-gap);

  --accent: var(--callout-info);
  --c-bg: color-mix(in srgb, var(--accent) var(--callout-mix-bg), transparent);
  --c-border: color-mix(in srgb, var(--accent) var(--callout-mix-border), #223047);
}
.callout--info{ --accent: var(--callout-info); }
.callout--warning{ --accent: var(--callout-warning); }
.callout--danger{ --accent: var(--callout-danger); }
.callout--success{ --accent: var(--callout-success); }

Thématisation par conteneur

Si vos docs sont intégrées dans une autre application, ne vous battez pas. Laissez l’hôte définir les accents en posant des variables sur le conteneur.

cr0x@server:~$ cat embed-example.html
<div class="partner-skin" style="--callout-info:#22c55e; --callout-warning:#a78bfa;">
  <aside class="callout callout--info" role="note">...</aside>
  <aside class="callout callout--warning" role="note">...</aside>
</div>

Ce style inline est parfois controversé. Si vous ne pouvez pas l’utiliser à cause du CSP, appliquez une classe et définissez les overrides dans une feuille CSS. Le principe importe : surchargez des tokens à une frontière, pas des règles CSS individuelles.

Modes de livraison : SVG inline par encadré vs sprite SVG vs symboles

Vous avez trois approches réalistes :

1. SVG inline par instance (simple, verbeux)
2. Sprite de symboles inline (dédupliqué, toujours local)
3. Sprite externe référencé par <use> (cacheable, maux de tête cross-origin)

Pattern A : SVG inline par encadré

Idéal lorsque vous avez peu d’encadrés par page et que vous voulez une fiabilité maximale. C’est aussi le plus simple à déployer dans du HTML statique généré depuis Markdown.

Pattern B : Sprite <symbol> inline dans le document

Insérez un SVG caché en haut de la page, définissez des symboles une fois, et référencez-les via <use>. Cela déduplique le markup tout en restant dans la même origine et en évitant des fetchs externes.

cr0x@server:~$ cat sprite-inline.html
<svg aria-hidden="true" style="position:absolute;width:0;height:0;overflow:hidden">
  <symbol id="icon-warning" viewBox="0 0 24 24">
    <path d="M12 9v4"></path>
    <path d="M12 17h.01"></path>
    <path d="M10.3 4.3 2.6 18a2 2 0 0 0 1.7 3h15.4a2 2 0 0 0 1.7-3L13.7 4.3a2 2 0 0 0-3.4 0z"></path>
  </symbol>
</svg>

<aside class="callout callout--warning">
  <div class="callout__icon" aria-hidden="true">
    <svg viewBox="0 0 24 24" focusable="false">
      <use href="#icon-warning"></use>
    </svg>
  </div>
  <div>...</div>
</aside>

Méfiez-vous des bizarreries navigateur avec des références externes et certains setups CSP ; les symboles inline sont généralement les moins problématiques.

Pattern C : Sprite externe

Utile pour les grands sites où le cache inter-pages compte. Risqué si votre environnement bloque le SVG cross-origin, si votre CSP le bloque, ou si votre pipeline ajoute une couche CDN qui réécrit des headers de manière surprenante. Les sprites externes compliquent aussi les workflows « export en un seul fichier HTML » (génération PDF, bundles offline).

Mon conseil : commencez par du SVG inline par encadré ou des symboles inline. Passez aux sprites externes seulement après avoir mesuré un vrai problème de payload et vérifié la compatibilité CSP dans vos environnements les plus restrictifs.

CSP et sécurité : conserver les icônes sans casser la politique

Les équipes sécurité ne font pas les difficiles pour le sport. Elles ont été formées par des incidents. Le SVG inline est généralement sûr quand c’est juste des chemins, sans scripts, sans gestionnaires d’événements, sans références externes et sans injection de contenu non fiable.

Règles sûres pour SVG (édition production)

• Utilisez des éléments simples : <path>, <circle>, <rect>. Évitez <foreignObject>.
• N’incluez pas de <script> dans le SVG. Ne riez pas ; ça arrive.
• Pas de gestionnaires d’événements inline comme onload ou onclick.
• Si les SVG sont fournis par les utilisateurs (contenu CMS), nettoyez fortement côté serveur.
• Évitez les références externes dans <use> à moins de contrôler headers et CSP de bout en bout.

Cette citation revient en ingénierie car elle s’applique douloureusement : si votre système d’icônes dépend de « ça devrait charger », vous avez intégré de l’espoir dans votre UI.

Où le CSP mord les encadrés spécifiquement

Ce n’est rarement le SVG lui-même. Ce sont les décisions autour :

• Styles inline bloqués : si vous thématisez via des attributs style inline, vous pourriez avoir besoin de style-src 'unsafe-inline' ou d’un nonce/hash. Évitez d’en dépendre. Préférez les classes et le CSS statique.
• Sprites externes bloqués : le navigateur peut refuser de charger <use href="...sprite.svg#id"> selon la politique, le cross-origin et les headers.
• Sanitizers qui suppriment le SVG : certains sanitizeurs HTML retirent entièrement le <svg> ou suppriment des attributs comme viewBox. Votre pipeline peut faire de la « sécurité » en cassant votre rendu.

Performance et fiabilité : ce qui ralentit et pourquoi

Ici, la performance n’est pas « le SVG est rapide ». La performance, c’est : la page devient utilisable rapidement, les encadrés ne déplacent pas la mise en page, et les icônes n’entraînent pas de reflows étranges. Le SVG inline aide car il évite un fetch de police et réduit les chances de swaps tardifs. Mais vous pouvez toujours vous tirer une balle dans le pied.

Coûts de performance courants

• Gonflement du HTML : répéter un chemin de 600 octets 60 fois devient du vrai poids. Parfois gzip vous sauve ; parfois non.
• CSS incontrôlé : des sélecteurs trop complexes sur un grand site de docs peuvent rendre le recalcul des styles plus coûteux que le SVG lui-même.
• Saut de mise en page : si vous ne réservez pas l’espace de l’icône, le texte peut sauter quand le SVG peint ou quand les polices se chargent.
• Coût de rendu : des SVG très détaillés (beaucoup de points, filtres) peuvent ralentir le paint. Gardez les icônes d’encadré simples.

Posture pratique de fiabilité

Pour les encadrés, préférez des icônes à traits (stroke) avec un viewBox cohérent (24×24 est courant). Limitez-vous à un petit jeu. Évitez les filtres. N’animez pas. Votre icône d’encadré n’est pas une image marketing. C’est un panneau de signalisation.

Blague #2 : La seule animation acceptable dans un encadré d’avertissement est votre rythme cardiaque quand vous réalisez que vous avez lancé la commande en production.

Méthode de diagnostic rapide

Quand les icônes d’encadré « cassent », vous voulez identifier vite le goulot : est-ce le markup, le CSS, le CSP, le sanitizeur ou la livraison ? Voici l’ordre qui fait gagner du temps.

Première étape : confirmez que l’icône existe dans le DOM

• Ouvrez les DevTools, inspectez l’encadré.
• Y a-t-il un élément <svg> avec un viewBox ?
• Les éléments <path> sont-ils présents ?

Si le SVG est absent : votre sanitizeur, renderer Markdown ou étape de template l’a probablement supprimé.

Deuxième étape : vérifiez les styles calculés pour taille et couleur

• Confirmez que le wrapper de l’icône a une largeur/hauteur explicite.
• Confirmez que le SVG utilise stroke: currentColor (ou fill) et que color est défini sur l’icône/le conteneur.
• Vérifiez si un reset global CSS écrase avec svg { display: inline; } ou modifie les dimensions.

Si le SVG est présent mais invisible : vous avez probablement des mismatches fill/stroke, un viewBox manquant, ou un token de couleur qui devient transparent.

Troisième étape : écartez CSP et références externes

• Regardez la console pour des erreurs de ressources bloquées.
• Si vous utilisez des sprites externes, testez avec un sprite de symboles inline pour isoler les problèmes cross-origin/CSP.
• Si la thématisation utilise des styles inline, vérifiez si le CSP bloque les styles inline.

Quatrième étape : mesurez le payload et la répétition

• Vérifiez la taille de transfert du HTML et du CSS.
• Comptez les encadrés par page et la répétition des données de path identiques.
• Si c’est énorme : envisagez un sprite de symboles ou une déduplication au build.

Tâches pratiques (commandes, sorties, décisions)

Voici des tâches réelles à lancer sur une machine Linux dans un job CI ou sur un serveur web pour diagnostiquer. Chaque tâche indique quoi chercher et la décision à prendre.

Task 1: Vérifier que le HTML généré contient encore des éléments SVG

cr0x@server:~$ rg -n "<svg|</svg>|viewBox" dist/**/*.html | head
dist/guide/backup.html:221:<svg viewBox="0 0 24 24" focusable="false">
dist/guide/backup.html:224:</svg>
dist/guide/restore.html:88:<svg viewBox="0 0 24 24" focusable="false">

Ce que signifie la sortie : Vous voyez des balises SVG et des attributs viewBox dans le rendu, pas seulement dans les templates source.

Décision : Si c’est vide, votre pipeline Markdown ou sanitizeur a supprimé le SVG. Corrigez la config du rendu avant de toucher au CSS.

Task 2: Détecter un viewBox manquant (cause classique d’icône invisible)

cr0x@server:~$ rg -n "<svg(?![^>]*viewBox)" dist/**/*.html | head
dist/guide/intro.html:54:<svg class="callout-icon">

Ce que signifie la sortie : Au moins un SVG manque de viewBox. Sans lui, le redimensionnement devient imprévisible et peut se réduire à rien.

Décision : Ajoutez un viewBox à chaque icône (standardisez sur 0 0 24 24). Ne « corrigez » pas ça avec des transforms CSS.

Task 3: Vérifier l’utilisation de sprites externes pouvant déclencher des problèmes CSP

cr0x@server:~$ rg -n "<use[^>]+href=\"https?://" dist/**/*.html | head
dist/guide/network.html:144:<use href="https://cdn.example.net/icons.svg#icon-info"></use>

Ce que signifie la sortie : Vous référencez un sprite externe via HTTP(S). Cela peut être bloqué par CSP, restrictions cross-origin ou fonctionnalités de confidentialité.

Décision : Préférez des symboles inline ou des sprites même origine sauf si vous avez vérifié headers et CSP dans l’environnement le plus strict.

Task 4: Identifier les styles inline de thématisation qui pourraient être bloqués par CSP

cr0x@server:~$ rg -n "style=\"[^\"]*--callout" dist/**/*.html | head
dist/guide/embed.html:12:<div class="partner-skin" style="--callout-info:#22c55e">

Ce que signifie la sortie : Des variables CSS sont définies via des styles inline. Si le CSP bloque les styles inline, la thématisation échouera silencieusement.

Décision : Déplacez les overrides vers une feuille basée sur classes, ou configurez le CSP avec nonces/hashes si vous avez vraiment besoin de styles inline.

Task 5: Confirmer que votre CSS définit stroke: currentColor ou fill: currentColor

cr0x@server:~$ rg -n "stroke:\s*currentColor|fill:\s*currentColor" dist/**/*.css
dist/assets/site.css:418:.callout__icon svg{stroke:currentColor;fill:none;stroke-width:1.9}

Ce que signifie la sortie : Les icônes héritent correctement la couleur, donc la thématisation via color ou tokens d’accent fonctionnera.

Décision : Si absent, choisissez une approche cohérente : icônes à traits (stroke=currentColor, fill=none) ou icônes pleines (fill=currentColor). Mixer les deux conduit à des icônes qui « disparaissent en mode sombre ».

Task 6: Repérer des resets CSS qui cassent le dimensionnement SVG

cr0x@server:~$ rg -n "svg\s*\{|svg\s*,|svg\s+\w" dist/**/*.css | head
dist/assets/reset.css:33:svg{display:inline}
dist/assets/reset.css:34:svg{vertical-align:middle}

Ce que signifie la sortie : Les resets globaux touchent au SVG. Pas toujours faux, mais souvent non revu.

Décision : Assurez-vous que votre composant définit explicitement SVG width/height/display. Ne comptez pas sur des resets globaux non examinés.

Task 7: Mesurer le gonflement HTML (répétition SVG inline)

cr0x@server:~$ wc -c dist/guide/backup.html
248312 dist/guide/backup.html

Ce que signifie la sortie : Cette page fait ~248 KB non compressés. Peut-être acceptable, peut-être excessif selon vos objectifs.

Décision : Si les pages sont systématiquement lourdes et contiennent des icônes répétées, pensez aux symboles inline pour dédupliquer.

Task 8: Compter les encadrés par page (prévoir répétition et risque de layout)

cr0x@server:~$ rg -c "class=\"callout\b" dist/guide/backup.html
27

Ce que signifie la sortie : 27 encadrés sur une page, c’est beaucoup. La répétition compte maintenant.

Décision : Si vous êtes dans la fourchette 20–50, le SVG inline par instance est probablement gaspilleur. Passez aux symboles ou à une inclusion au build.

Task 9: Vérifier le comportement gzip/brotli sur les assets statiques (les octets comptent)

cr0x@server:~$ gzip -c dist/guide/backup.html | wc -c
42186

Ce que signifie la sortie : Gzip réduit 248 KB à ~42 KB. Les chemins SVG répétitifs se compressent bien.

Décision : Si la taille compressée est déjà petite, ne sur-design pas la déduplication. Si elle reste grande, passez aux symboles ou réduisez la complexité des icônes.

Task 10: Vérifier les headers serveur pour un CSP qui pourrait bloquer styles ou références SVG

cr0x@server:~$ curl -sI https://docs.example.internal/guide/backup | rg -i "content-security-policy|x-content-type-options|x-frame-options"
content-security-policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN

Ce que signifie la sortie : Les styles inline sont bloqués (style-src 'self' sans 'unsafe-inline' ni nonces). Les data: pour images sont autorisés.

Décision : N’utilisez pas d’attributs style inline pour thématiser ; gardez les tokens dans le CSS. Pour les sprites externes, assurez-vous qu’ils sont même origine ('self').

Task 11: Valider que votre sanitizeur SVG ne supprime pas d’attributs requis

cr0x@server:~$ node -p "require('fs').readFileSync('dist/guide/backup.html','utf8').includes('viewBox=')"
true

Ce que signifie la sortie : Au moins un viewBox a survécu au pipeline.

Décision : Si false, corrigez la allowlist du sanitizeur (viewBox, aria-*, role) ou arrêtez de sanitizer deux fois des artefacts de build fiables.

Task 12: Trouver des icônes avec fill=none qui devraient être pleines

cr0x@server:~$ rg -n "fill=\"none\"" dist/**/*.html | head
dist/guide/alerts.html:77:<path fill="none" d="M12 2a10 10 0 1 0 0 20"></path>

Ce que signifie la sortie : Certains chemins forcent explicitement le remplissage à none. Si votre jeu d’icônes inclut des icônes pleines, cela peut les rendre invisibles.

Décision : Normalisez les icônes : retirez les attributs fill et contrôlez via CSS, ou assurez-vous que votre composant supporte les deux avec des classes explicites.

Task 13: Détecter des données de path dupliquées qui devraient être un symbole

cr0x@server:~$ rg -n "M10\.3 4\.3 2\.6 18" dist/**/*.html | wc -l
54

Ce que signifie la sortie : Le même chemin de triangle d’avertissement apparaît 54 fois. C’est de la duplication.

Décision : Si ça augmente, passez à un sprite de symboles inline ou à des inclusions au build pour dédupliquer.

Task 14: Confirmer que les overrides de variables CSS s’appliquent réellement (grep rapide des tokens)

cr0x@server:~$ rg -n "--callout-(info|warning|danger|success)" dist/**/*.css
dist/assets/site.css:12:--callout-info:#60a5fa;
dist/assets/site.css:13:--callout-warning:#fbbf24;
dist/assets/site.css:14:--callout-danger:#fb7185;
dist/assets/site.css:15:--callout-success:#34d399;

Ce que signifie la sortie : Les tokens existent dans le CSS déployé, pas seulement dans votre repo source.

Décision : Si les tokens manquent, votre step de build supprime un fichier ou votre bundler a tree-shaké des variables par erreur.

Trois mini-récits issus de la vie en entreprise

Mini-récit 1 : L’incident causé par une mauvaise hypothèse

Une équipe entretenait un manuel d’opérations interne utilisé pendant les incidents. Le manuel contenait des encadrés « Danger », « Warning » et « Note ». Les icônes étaient rendues via une police d’icônes hébergée sur un domaine d’actifs partagé. L’hypothèse : « La police est mise en cache partout, donc c’est gratuit. »

Puis un changement de sécurité a été déployé. Le proxy d’entreprise a commencé à filtrer les réponses de polices distantes à moins qu’elles ne proviennent d’une origine allowlistée. Personne n’a coordonné avec l’équipe docs parce que, dans une grande entreprise, le site de docs est « juste du contenu statique ».

Pendant un incident réel, les intervenants ont ouvert le manuel depuis un profil navigateur durci. Toutes les icônes d’avertissement sont devenues des carrés vides. Pire, les titres d’encadrés étaient subtils et l’icône faisait la majeure partie du travail visuel. Un ingénieur a manqué une note « ne pas exécuter deux fois » et a relancé un script de remédiation. Ça n’a pas détruit le monde, mais cela a prolongé l’incident et créé une incohérence de données à nettoyer ensuite.

La discussion post-incident n’a pas porté sur les polices. Elle a porté sur les hypothèses : le site docs dépendait d’une police distante non tracée, et cette dépendance a compté au moment où les docs étaient le plus nécessaires.

La correction a été franche et correcte : SVG inline pour les quatre types d’encadrés, livrés avec la page. Les icônes sont devenues partie intégrante de l’artefact, pas un pari réseau. L’équipe a aussi augmenté le poids visuel du titre pour que l’icône cesse d’être le signal principal.

Mini-récit 2 : L’optimisation qui a mal tourné

Un autre groupe a construit un design system soigné pour les outils internes. Ils ont remplacé les polices d’icônes par un unique sprite SVG externe pour réduire la duplication HTML. Il était servi depuis un CDN et référencé via <use href="...icons.svg#id">. Élégant sur le papier.

Puis ils ont reçu des rapports : « Icônes manquantes dans Safari », « Icônes manquantes dans les PDFs », « Icônes manquantes dans les vues intégrées ». Les icônes manquantes n’étaient pas aléatoires ; elles corrélaient avec des environnements où les pages étaient rendues dans des contextes restreints. Certains outils intégraient d’autres outils en iframe avec des headers CSP différents. Certains utilisateurs exportaient des pages en PDF via un service qui ne récupérait pas les sous-ressources cross-origin. Certains navigateurs traitent différemment les références externes <use> selon les headers et le cache.

L’équipe a tenté de corriger avec des règles de cache et du tuning des headers. Ça a aidé à un endroit et cassé ailleurs. Classique. Ils avaient échangé quelques kilo-octets de markup dupliqué contre un problème de systèmes distribués impliquant origines, headers et renderers.

Le compromis final a été sensé : sprites de symboles inline pour les applis nécessitant de la fiabilité (outils d’incident), sprites externes seulement pour des pages marketing publiques où le cache importait et le CSP pouvait être uniformisé. Le design system documentait les deux patterns et a rendu le choix fiable par défaut.

Mini-récit 3 : La pratique ennuyeuse qui a sauvé la mise

Une équipe plateforme docs exécutait un générateur de site statique avec un sanitizeur HTML strict parce que le contenu était rédigé par de nombreuses équipes. Le support SVG était initialement désactivé « pour la sécurité ». Plutôt que de contourner le sanitizeur, ils ont fait la chose ennuyeuse : créé une petite allowlist pour un sous-ensemble SVG contraint utilisé uniquement pour les icônes.

L’allowlist autorisait <svg> avec viewBox, focusable et attributs ARIA ; autorisait <path> avec d ; et supprimait le reste. Pas de scripts. Pas de foreignObject. Pas de références externes. Ils ont aussi imposé une taille d’icône standard et retiré les styles inline.

Des mois plus tard, une équipe a accidentellement collé un SVG complexe exporté d’un outil de design dans un encadré. Le sanitizeur l’a réduit à rien d’utile, et la build a échoué à cause d’une règle lint détectant « icône vide ». L’auteur a reçu un message d’erreur clair avec des instructions de remédiation.

Ce n’était pas glamour. Mais ça a empêché une classe de problèmes de sécurité et de performance d’entrer sur le site, et ça a fait des « icônes SVG dans les encadrés » une valeur sûre plutôt qu’une exception nécessitant une dérogation sécurité.

Erreurs courantes : symptômes → cause profonde → correction

1) Symptom : les icônes s’affichent comme des cases vides ou des lettres aléatoires

Cause : Vous utilisez encore des polices d’icônes quelque part, et la police ne s’est pas chargée ou a été substituée.

Correction : Supprimez les polices d’icônes pour les encadrés. Remplacez-les par du SVG inline. Cherchez aussi du CSS résiduel comme .icon:before { content: "\e018"; font-family: ... } qui traîne.

2) Symptom : le SVG est dans le DOM mais rien n’est visible

Cause : ViewBox manquant, ou votre SVG utilise des paths remplis tandis que votre CSS force fill: none, ou la couleur se résout en transparent.

Correction : Standardisez tous les icônes avec un viewBox ; décidez stroke vs fill ; définissez stroke: currentColor ou fill: currentColor en conséquence ; vérifiez la color calculée sur le conteneur d’icône.

3) Symptom : icônes visibles sur certaines pages mais manquantes sur d’autres

Cause : Références de sprites externes bloquées par CSP ou conditions cross-origin, ou vos chemins de sortie de build diffèrent selon les sections.

Correction : Utilisez des symboles inline pour les docs et outils internes. Si vous devez utiliser des sprites externes, gardez-les même origine et vérifiez CSP et headers dans tous les contextes (iframes, services d’export PDF inclus).

4) Symptom : le layout de l’encadré saute au chargement

Cause : L’espace d’icône n’est pas réservé (pas de width/height sur le wrapper), ou les polices se chargent tard et modifient la hauteur de ligne.

Correction : Donnez un taille fixe au wrapper d’icône et définissez le SVG en display: block. Stabilisez la typographie des encadrés et évitez les swaps de police pour l’UI critique.

5) Symptom : le mode sombre rend les bordures sales ou à faible contraste

Cause : Les couleurs dérivées ont été réglées uniquement pour le mode clair ; le mélange produit des bordures boueuses en sombre.

Correction : Définissez des pourcentages de mix séparés pour les thèmes clair/sombre ou des tokens de bordure explicites par thème. Testez le contraste, ne vous fiez pas à l’œil.

6) Symptom : les lecteurs d’écran annoncent « graphic » à répétition ou lisent le titre de l’icône

Cause : Le SVG n’est pas marqué décoratif, ou vous avez utilisé <title> dans le SVG sans intention.

Correction : Pour les icônes décoratives : aria-hidden="true". Pour les icônes signifiantes : fournissez un label accessible et ne dupliquez pas le titre de l’encadré.

7) Symptom : certaines icônes sont verticalement mal alignées par rapport au texte

Cause : Le SVG est en niveau inline et s’aligne sur la baseline ; les rapports d’aspect viewBox diffèrent entre icônes.

Correction : Utilisez display: block sur le SVG, un wrapper de taille fixe, et standardisez les icônes sur le même viewBox et le même centre visuel.

8) Symptom : les icônes disparaissent après une « durcissement » de sécurité

Cause : Le sanitizeur supprime les éléments/attributs SVG, ou le CSP bloque les styles inline utilisés pour la thématisation.

Correction : Créez une allowlist SVG explicite pour les icônes ; retirez la thématisation via styles inline ; assurez-vous que tous les attributs requis (viewBox, aria-hidden) soient autorisés.

Checklists / plan pas à pas

Étapes : migrer des polices d’icônes vers des encadrés SVG inline

1. Inventaire des encadrés actuels. Listez les types et où ils apparaissent (docs, UI produit, emails, exports).
2. Définissez l’ensemble minimal d’icônes. Info, warning, danger, success suffit généralement. Moins d’icônes = moins d’incohérences.
3. Normalisez la géométrie des icônes. Choisissez un viewBox standard (souvent 0 0 24 24) et une épaisseur de trait cohérente.
4. Choisissez style trait ou plein. Les jeux mixtes sont possibles, mais nécessitent du CSS supplémentaire. Restez simple sauf si le design exige le contraire.
5. Construisez le composant avec des tokens. Utilisez --accent, calculez --c-bg et --c-border.
6. Rendez les icônes décoratives par défaut. Exigez des titres visibles. Masquez les SVG avec aria-hidden sauf raison spécifique.
7. Testez sous CSP strict. Testez spécifiquement avec styles inline bloqués et polices distantes bloquées.
8. Testez le mode sombre et thèmes haute-contraste. Vérifiez les bordures et le contraste des textes.
9. Ajoutez des lint HTML/SVG en CI. Détectez viewBox manquants, chemins vides ou attributs retirés.
10. Mesurez le payload et la répétition. Si gonflement réel, passez de SVG inline par instance à symboles inline.
11. Documentez le pattern. Pas un roman : un exemple, liste do/don’t et tokens à surcharger.
12. Supprimez les dépendances à l’ancienne police d’icônes. Ne laissez pas de CSS fantôme. Le CSS fantôme revient toujours vous hanter.

Checklist : préparation au release pour les icônes d’encadrés

• Tous les SVG d’encadré incluent viewBox et rendent correctement en 1x et 2x sans être rognés.
• Les icônes héritent la couleur via currentColor (trait ou remplissage) et sont visibles en mode sombre.
• Les titres d’encadré sont visibles et transmettent le type sans dépendre de la couleur de l’icône.
• Les icônes décoratives ont aria-hidden="true".
• Aucune dépendance à une police externe d’icônes ne subsiste.
• Les pages s’affichent correctement avec CSP : pas de style inline requis, pas de ressources bloquées.
• Performance : les icônes ne provoquent pas de sauts de layout ; les dimensions du wrapper sont fixes.

FAQ

1) Pourquoi du SVG inline plutôt qu’une bibliothèque d’icônes ?

Les bibliothèques conviennent si vous contrôlez la chaîne de build et pouvez garantir un rendu cohérent. Pour les encadrés, vous voulez la surface de dépendance la plus petite et la plus prévisible. Le SVG inline est explicite et portable, surtout pour la documentation statique et les runbooks d’incident.

2) Dois-je utiliser des icônes pleines ou à traits ?

Choisissez une approche pour tout le système d’encadrés. Les icônes à traits avec stroke: currentColor sont faciles à thématiser et tiennent bien à petite taille. Les icônes pleines conviennent aussi, mais assurez-vous de contrôler fill de manière cohérente et d’éviter les sémantiques mixtes.

3) L’utilisation de color-mix() est-elle sûre ?

Elle est largement supportée dans les navigateurs modernes, mais si vous avez des exigences legacy, vous devrez peut-être fournir des tokens explicites (couleurs de fond/bordure précalculées). Opérationnellement : si vous ne pouvez pas contrôler la base navigateur, ne calculez pas les couleurs à l’exécution.

4) Comment éviter que le HTML devienne énorme si j’inline les SVG partout ?

Utilisez un sprite de symboles inline (<symbol>) en haut du document et référencez avec <use>. Ça déduplique sans fetch cross-origin. Si votre pipeline le permet, incluez aussi les icônes comme partials.

5) Les icônes SVG inline violent-elles le CSP ?

Le SVG inline n’est pas du script inline. Les problèmes viennent des scripts dans le SVG, des gestionnaires d’événements ou des références externes. Limitez les SVG à des formes simples et sanitizez si le contenu est non fiable. Évitez aussi les attributs style inline pour la thématisation si le CSP les bloque.

6) Quel élément HTML est le plus sémantique pour un encadré ?

<aside> est un bon choix par défaut. Ajoutez role="note" si ça aide les technologies d’assistance. Évitez role="alert" sauf si l’encadré représente une information urgente et dynamique nécessitant une annonce immédiate.

7) Mon sanitizeur supprime viewBox. Puis-je m’en passer ?

Vous pouvez, mais vous ne devriez pas. Sans viewBox, le redimensionnement est fragile et peut produire des rendus vides. Corrigez la allowlist du sanitizeur. Si votre plateforme ne peut pas autoriser viewBox en toute sécurité, il vous faut une autre stratégie (par exemple rendu serveur vers un markup sûr), pas des hacks CSS.

8) Comment garantir l’alignement parfait de l’icône avec le titre quel que soit la police ?

Utilisez un wrapper d’icône de taille fixe et définissez le SVG en display: block. Ajustez la marge-top seulement si nécessaire, mais préférez l’alignement via line-height cohérente et la boîte d’icône. Ne dépendez pas de l’alignement sur la baseline pour le SVG.

9) Puis-je encoder le SVG en data URL ?

Vous pouvez, mais c’est généralement pire pour la maintenabilité et ça peut être bloqué selon le CSP (img-src). Le SVG inline est plus clair, plus simple à thématiser et plus facile à auditer.

10) Mes docs sont en Markdown et le renderer supprime le HTML. Que faire ?

Il vous faut soit une extension Markdown pour les encadrés qui rend du HTML fiable au build, soit un système de shortcodes composants. Ne demandez pas aux auteurs de lutter contre le renderer ; facilitez la « bonne manière ».

Conclusion : prochaines étapes pour ne pas vous embarrasser plus tard

Les encadrés sont petits, mais ils se situent à l’intersection de la fiabilité et de l’attention humaine. SVG inline + variables CSS est le choix pragmatique car il réduit les dépendances, survit aux environnements stricts et garde la thématisation simple.

Prochaines étapes :

1. Standardisez quatre types d’encadrés et un petit set d’icônes partagé avec un viewBox et une épaisseur de trait communs.
2. Implémentez le composant basé sur tokens (accent/fond/bordure) et cachez les icônes décoratives aux technologies d’assistance.
3. Exécutez les tâches de diagnostic ci-dessus en CI : vérifiez viewBox manquants, références de sprites externes accidentelles et CSS de polices d’icônes résiduels.
4. Testez sous votre profil CSP le plus strict et en mode sombre avant de publier.
5. Si vous atteignez un gonflement de payload, passez aux symboles inline — n’allez pas tout de suite vers des sprites externes sauf si vous contrôlez les headers partout.