Image

1import { Image } from '@/ui/Display'23<Image4  src="/architecture.png"5  alt="Request flow from the load balancer to three regions"6  width={1600}                    // reserves the ratio before loading7  height={900}8  ratio="16 / 9"9  fit="contain"                   // a diagram: never crop it10  loading="lazy"                  // but NEVER on the hero11/>1213// Responsive sources. One file for every screen wastes megabytes on the14// connections least able to afford them.15<picture>16  <source type="image/avif" srcSet="/hero.avif 1x, /hero@2x.avif 2x" />17  <source type="image/webp" srcSet="/hero.webp 1x, /hero@2x.webp 2x" />18  <img19    src="/hero.jpg"20    alt="Deployment dashboard showing three healthy regions"21    width={1600}22    height={900}23    sizes="(max-width: 640px) 100vw, 640px"24    fetchPriority="high"          // it is the largest contentful paint25  />26</picture>2728// Failure is a state, not an accident. The browser's broken-image icon29// looks like the product is broken.30const [failed, setFailed] = React.useState(false)3132{failed ? (33  <div className="ds-image__error">34    <ImageOff aria-hidden /> Image unavailable35  </div>36) : (37  <img src={src} alt={alt} onError={() => setFailed(true)} />38)}3940// A complex diagram needs more than one sentence — and everyone benefits.41<img src="/arch.png" alt="System architecture" aria-describedby="arch-desc" />42<p id="arch-desc">Requests enter through the load balancer, which…</p>

<!-- Dimensions let the browser compute the ratio before the bytes arrive. -->
<img
  src="/architecture.png"
  alt="Request flow from the load balancer to three regions"
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>

<!-- Decorative: alt="" removes it from the accessibility tree. A MISSING
     alt does not — some screen readers read the filename instead. -->
<img src="/texture.svg" alt="" />

<!-- Caption is content everyone reads; alt is for people who cannot see it.
     They should not say the same thing. -->
<figure>
  <img src="/flow.png" alt="Three regions receiving traffic in parallel" />
  <figcaption>
    Request flow from the load balancer to three regions. Failed health
    checks route to the previous build.
  </figcaption>
</figure>

<!-- The hero is the largest contentful paint: eager, and prioritised. -->
<img src="/hero.jpg" alt="…" fetchpriority="high" loading="eager" />

.ds-image {
  position: relative;
  overflow: hidden;
  border-radius: var(--radius-lg);
  /* Visible while loading, behind a transparent PNG, and around a contained
     image. A transparent box shows the page through the gaps. */
  background: var(--ds-surface-inset);
  /* The single most valuable line here: the space is held before the bytes
     arrive, so nothing below reflows. */
  aspect-ratio: var(--ratio, 16 / 9);
}

.ds-image img {
  inline-size: 100%;
  block-size: 100%;
  /* Never absent: without it, an image whose intrinsic ratio differs from
     its box is squashed rather than cropped. */
  object-fit: var(--fit, cover);
  object-position: center;
  display: block;
}

/* Diagrams and logos: losing an edge changes the meaning. */
.ds-image--contain img { object-fit: contain; padding: 8px; }

.ds-image img {
  opacity: 0;
  transition: opacity 180ms;
}
.ds-image img[data-loaded='true'] { opacity: 1; }

/* A white product shot on a white surface has invisible boundaries. */
.ds-image--bordered { box-shadow: inset 0 0 0 1px var(--ds-border-subtle); }

/* Text over a photograph: contrast is not assertable without this. */
.ds-image--overlay::after {
  content: '';
  position: absolute;
  inset: 0;
  background: linear-gradient(to top, rgb(0 0 0 / 0.6), transparent 60%);
}

@media (prefers-reduced-motion: reduce) {
  .ds-image img { transition: none; }
}