Image

Encapsule <img> avec les garanties qu'il n'impose pas par défaut : espace réservé (anti-CLS), lazy loading, support WebP, états de chargement et d'erreur. Wraps <img> with the guarantees it doesn't enforce by default: reserved space (anti-CLS), lazy loading, WebP support, loading and error states.

DémonstrationDemo

Par défaut — lazy, sans skeletonDefault — lazy, no skeleton

object-fit: cover / containobject-fit: cover / contain

État d'erreur — repli si l'image échoueError state — fallback on failed load

Règles absoluesAbsolute rules

width et height obligatoires — sinon le CLS que le composant existe pour éviter se produit quand mêmewidth and height are required — otherwise the CLS this component exists to prevent still occurs
alt obligatoire sauf decorative — WCAG 1.1.1alt required unless decorative — WCAG 1.1.1
priority sur une seule image par page (la véritable LCP)priority on at most one image per page (the true LCP)
skeleton par défaut sur chaque petite image inline — réservé aux images lourdes/heroskeleton by default on every small inline image — reserved for heavy/hero images

Tokens de composantComponent tokens

Token CSS	RéférenceReference	ValeurValue
`--agtc-component-image-skeleton-background`	`semantic.color.background.subtle`	#f0f0f0
`--agtc-component-image-skeleton-background-pulse`	`semantic.color.background.hover`	#fafafa
`--agtc-component-image-fallback-background`	`semantic.color.background.subtle`	#f0f0f0
`--agtc-component-image-fallback-icon`	`semantic.color.text.secondary`	#646464
`--agtc-component-image-fallback-text`	`semantic.color.text.secondary`	#646464

AccessibilitéAccessibility

alt manquant sans decorative : avertissement console (WCAG 1.1.1)Missing alt without decorative: console warning (WCAG 1.1.1)
Image décorative : alt="" + aria-hidden="true"Decorative image: alt="" + aria-hidden="true"
État de repli : role="img" + aria-label reprenant le texte alternatifFallback state: role="img" + aria-label carrying the same alt text
Animation du skeleton désactivée sous prefers-reduced-motionSkeleton animation disabled under prefers-reduced-motion

ImplémentationImplementation

<!-- De base — width/height obligatoiresBasic — width/height required -->
<agtc-image src="photo.jpg" alt="…" width="800" height="450"></agtc-image>

<!-- WebP avec repliwith fallback -->
<agtc-image src="photo.jpg" src-webp="photo.webp" alt="…" width="800" height="450"></agtc-image>

<!-- Skeleton en option (images lourdes/hero)Opt-in skeleton (heavy/hero images) -->
<agtc-image src="hero.jpg" alt="…" width="1200" height="630" skeleton></agtc-image>

<!-- LCP -->
<agtc-image src="hero.jpg" alt="…" width="1200" height="630" priority></agtc-image>

DOs et DON'TsDOs and DON'Ts

À faireDo

Toujours fournir width et heightAlways provide width and height
Réserver priority à la véritable image LCPReserve priority for the true LCP image
Utiliser skeleton pour les images lourdes/hero seulementUse skeleton for heavy/hero images only

À éviterDon't

Omettre width/heightOmitting width/height
decorative sur une image porteuse de sensdecorative on a meaningful image
priority sur plus d'une image par pagepriority on more than one image per page

UX Patterns Reference

Patterns approved via the ux-pattern-review workflow (ADR-036). Decision: all approved, skeleton explicitly requested for v1.

Pattern	Source	Applied	Justification
Decorative vs meaningful image distinction	WCAG 1.1.1 / NN/g	✅	Mirrors the pattern already approved on `agtc-icon` — `decorative` prop → `alt=""` + `aria-hidden`
Skeleton screen while loading (opt-in)	NN/g — Skeleton Screens 101	✅	Included in v1 per explicit human decision (2026-07-21) — opt-in via `skeleton`, not on by default, since it's overkill for small inline images
Graceful fallback on load failure	General error-handling principle (no dedicated reference-source article found for images specifically)	✅	Icon + visible alt text instead of a broken-image hole
`object-fit` configurable	Design system decision (not a reference-source pattern)	✅	`fit` prop, default `cover` — consistent cropping across avatar/illustration usages