Catálogo · Documentación
Ejemplo
Una vista previa en vivo con el código debajo, en un mismo marco y con la anchura que le asignes.
Encaja mejor en: documentación — una página que muestra un ejemplo en vivo con su código
Ejemplo
Una vista previa de un botón con su marcado debajo.
<button class="luz-btn luz-btn--primary" type="button">Save changes</button>The preview, and the markup that makes it under it. The width of the frame follows --luz-example-w.
Problemas conocidos
No se conocen.
Código
Copiar el marcado
import "@luz-ds/catalog/components/example.css";<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/example.min.css" integrity="sha384-6PMwsV5nwigGpYPyw438GJj5Dk1YJ3/7pLnMLEe0VWvR1iM/pgM131Vldh0IEwh7" crossorigin="anonymous">Una figura con la vista previa y, debajo, el código. El código es opcional:
<figure class="luz-example">
<div class="luz-example__preview">
<div class="luz-example__frame">
<button class="luz-btn luz-btn--primary" type="button">Save changes</button>
</div>
</div>
<div class="luz-example__code">
<pre class="luz-code-block" data-lang="html" tabindex="0" aria-label="Markup of the example"><code><button class="luz-btn luz-btn--primary" type="button">Save changes</button></code></pre>
</div>
</figure>Variantes y opciones
No hay modificadores. La anchura se controla con una propiedad personalizada.
| Clase o propiedad | Efecto |
|---|---|
.luz-example | En un <figure>: una caja enmarcada con un borde redondeado sobre la superficie. La vista previa y el código comparten el marco |
.luz-example | El marcado en vivo, con espacio interior alrededor del marco |
.luz-example | Dentro de la vista previa: ocupa su anchura o la que indique --luz-example-w (nunca más), y está centrado. Es un contenedor de tamaño |
.luz-example | Opcional, debajo de la vista previa, a todo su ancho y con una línea encima. Si contiene un pre.luz-code-block, este pierde su propio borde |
--luz-example-w | La anchura del marco. Asígnala al marco: style="--luz-example-w: 20rem" equivale a un móvil. De forma predeterminada, ocupa toda la vista previa |
Cómo funciona
CSS de components/example.css de @luz-ds/catalog sobre el bloque de código y el resaltado de core.
- La vista previa y el código comparten un marco, así que se entienden como un único ejemplo. Las líneas largas se desplazan dentro del bloque de código y nunca ensanchan la figura.
- La anchura del marco es
min(100%, var(--luz-example-w, 100%)): si supera el espacio disponible, la figura no se ensancha. - El marco es un contenedor de tamaño (
container-type: inline-size). Un botón de bloque ocupa el marco, no la ventana, y puedes hacer que una regla propia responda al marco con@container. - Escribe el marcado una vez y muéstralo de dos formas, como vista previa y como código escapado: quien lee ve lo que va a copiar.
Sin JavaScript
El marco no cambia. El bloque de código es texto sin formato en una región desplazable que puede recibir el foco, sin el resaltado ni el botón de copia del script de core.
Teclado y ARIA
- Orden: primero los controles de la vista previa y después el bloque de código.
- Bloque de código: conserva
tabindex="0"y unaria-labelen<pre>: el bloque se desplaza y, sin esos atributos, quien usa el teclado no puede llegar hasta él ni saber qué es. - Vista previa: es interactiva, así que su contenido funciona como en cualquier otro sitio. Incluye las imágenes que no deban usarse en Qué hacer y qué no, cuya zona de ejemplo es inerte.
La pestaña Diseño incluye Contraste y foco.
Diseño
Cuándo usarlo
Usa el ejemplo para mostrar una pieza y el marcado que la crea en un mismo marco, con el código debajo de la vista previa.
- Un componente, un patrón o un fragmento que quien lee pueda copiar.
- Una pieza cuyo aspecto dependa de su anchura: ajusta la anchura del marco.
Cuándo no usarlo
No uses el ejemplo para mostrar un error ni código que no tenga una vista previa.
- Las imágenes de errores van en Qué hacer y qué no, que es inerte.
- El código que no tenga nada que mostrar, como un comando, va en un bloque de código normal.
Qué hacer y qué no
Cómo escribir el contenido
- La frase anterior al ejemplo explica qué muestra, en imperativo: «Añade la clase principal para crear la acción principal».
- El código es exactamente el marcado de la vista previa. Usa palabras reales, no «Lorem ipsum» ni «Botón».
- Menciona en la frase la única clase o atributo que enseña el ejemplo, para que quien lee sepa dónde buscarlo en el código.
- Ponle un nombre al bloque de código: «Marcado del ejemplo» o, si hay varios, «Marcado del botón principal».
Contraste y foco
La vista previa se muestra sobre la superficie del marco. El bloque de código conserva los colores de core; consulta el bloque de código.
| Elemento | Color sobre fondo | Claro | Oscuro | Alto contraste | Mínimo |
|---|---|---|---|---|---|
Texto de la vista previa | --luz-text-primary on --luz-surface | 16.5:1 | 14.0:1 | 21.0:1 | 4.5:1 |
Anillo de foco | --luz-focus-ring on --luz-surface | 5.9:1 | 7.2:1 | 21.0:1 | 3:1 |
Medido a partir de los valores de los tokens de cada modo y redondeado hacia abajo. El mínimo es el de WCAG 2.2 AA: 4,5:1 para texto y 3:1 para anillos de foco, bordes e iconos.
- Foco: los controles de la vista previa y del bloque de código conservan el anillo de core, de 2 px,
--luz-focus-ring. - Bordes: el borde del marco (
--luz-divider) es decorativo y no tiene un mínimo. - Anchura: el marco nunca supera el espacio disponible, así que la página no se desplaza horizontalmente a 320px.
Tokens que usa
Los 4 tokens que leen las reglas de .luz-example de components/example.css del catálogo, agrupados por familia. Cada familia enlaza a su página, donde están los valores de todos los modos. En Figma son variables con los mismos nombres; consulta Tokens en Figma.
- Spacing and sizing
--luz-space-md- Radius
--luz-radius-md
La pestaña Código incluye Teclado y ARIA.