Imagen

Código

Copiar el marcado

<div class="luz-image">
  <picture>
    <source type="image/avif" srcset="dunes-640.avif 640w, dunes-1280.avif 1280w" sizes="(min-width: 768px) 50vw, 100vw">
    <source type="image/webp" srcset="dunes-640.webp 640w, dunes-1280.webp 1280w" sizes="(min-width: 768px) 50vw, 100vw">
    <img src="dunes-1280.jpg" srcset="dunes-640.jpg 640w, dunes-1280.jpg 1280w" sizes="(min-width: 768px) 50vw, 100vw"
      width="1280" height="720" alt="Sand dunes under a low sun" loading="lazy" decoding="async">
  </picture>
</div>

Variantes y opciones

Un modificador establece la forma. Si no se usa ninguno, el marco tiene una proporción de 16:9.

Cómo funciona

Un <div> de proporción fija alrededor de un <picture> nativo, con estilos de @luz-ds/core. Sin JavaScript.

• La imagen llena el marco y se recorta para ajustarse a él.
• El marco es una superficie lisa --luz-surface-strong: se muestra sin imagen, mientras se carga o si falla. El texto alternativo de una imagen que no se carga aparece sobre ella, al igual que las imágenes PNG y SVG transparentes.
• LUZ no incluye ninguna imagen de sustitución: la página no solicita nada que no haya especificado.

Sin JavaScript

No cambia nada: el marco y la imagen se crean con HTML y CSS. Sin CSS, la imagen aparece con su tamaño original.

Teclado y ARIA

El marco no tiene ninguna interacción propia.

• Los lectores de pantalla anuncian el <img> mediante su texto alternativo; un marco vacío no anuncia nada.
• No añadas un rol ni un aria-label al marco.
• Si la imagen es un enlace, su nombre procede del texto alternativo, que debe indicar adónde lleva.

El contraste y el foco están en la pestaña Diseño.

Diseño

Cuándo usarlo

Usa el marco de imagen para mostrar una imagen en un cuadro de forma fija, como la portada de una tarjeta o la cabecera de un artículo, cuando la imagen pueda faltar.

• Contenido de otras personas o de un sistema de gestión de contenidos.
• Una página creada antes de disponer de las imágenes.

Cuándo no usarlo

No lo uses con imágenes que deban conservar su forma, como gráficos o capturas de pantalla: el marco las recorta.

• Para un gráfico o diagrama con un pie, usa una figura.
• Para los iconos y logotipos, usa un <img> o un SVG con su tamaño original.
• No uses nunca un marco vacío como sustituto de una imagen informativa: si falta, indícalo con texto.

Qué hacer y qué no

Cómo escribir el contenido

Añade a cada imagen real un texto alternativo que describa lo que muestra en una frase sencilla.

• Usa alt="" si la imagen es decorativa o el texto que la acompaña ya dice lo mismo.
• El marco recorta la imagen: aleja de los bordes el texto y los detalles esenciales, y describe lo que sigue visible.
• Establece width y height con el tamaño original de la imagen para que la página no dé saltos mientras se carga.
• Añade loading="lazy" solo a las imágenes que quedan más abajo: las que se ven al abrir la página deben cargarse de inmediato.
• No incluyas texto en las imágenes.

Contraste y foco

El marco usa la superficie intensa; si una imagen no se carga, su texto alternativo aparece en color de texto principal sobre ella.

Medido a partir de los valores de los tokens de cada modo, redondeado hacia abajo. Los requisitos son los mínimos de WCAG 2.2 AA: 4,5:1 para el texto y 3:1 para los anillos de foco, los bordes y los iconos.

• Foco: el marco no lo recibe.
• Imágenes: sus colores son propios.

Tokens que usa

Los 3 tokens que lee components/image.css, agrupados por familia. Cada familia enlaza a su página, con los valores de cada modo. En Figma son variables con los mismos nombres: consulta Tokens en Figma.

Color

--luz-surface-strong, --luz-text-primary

Radius

--luz-radius-md

El teclado y ARIA están en la pestaña Código.