Catálogo · Documentación
Cabecera de página
La parte superior de una página de documentación: el epígrafe, el título, una frase y las etiquetas que indican de qué trata.
Encaja mejor en: documentación — la parte superior de una página de documentación
Ejemplo
La cabecera de una página sobre cómo instalar una herramienta de línea de comandos.
A picture of the head: it holds a title of its own, so it is hidden from assistive technology on this page. Its text is in the markup below.
The chips wrap on a narrow screen.
Problemas conocidos
No se conocen.
Código
Copiar el marcado
import "@luz-ds/catalog/components/doc-header.css";<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/doc-header.min.css" integrity="sha384-cVHBijhO5S1m513QmZHN7btnqgne60iGIX8ZA3KRh9BkZafEAbeVcEurGxtfGbg+" crossorigin="anonymous">La cabecera, como primer elemento hijo del contenido:
<header class="luz-doc-header">
<p class="luz-doc-header__eyebrow">Guides · Setup</p>
<h1>Install the command line tool</h1>
<p class="luz-doc-header__lead">Add the tool to a project and check that it runs, in about two minutes.</p>
<ul class="luz-doc-header__meta">
<li>Version 2</li>
<li>macOS, Linux and Windows</li>
<li><a href="#known-issues">No known issues</a></li>
</ul>
</header>Variantes y opciones
No hay modificadores. La cabecera es una clase aplicada a un <header> nativo con cuatro partes.
| Clase | Efecto |
|---|---|
.luz-doc-header | En un <header> del contenido: una columna, con separación entre sus partes y espacio debajo. Su h1 usa --luz-text-4xl, o --luz-text-2xl a 640px o menos |
.luz-doc-header | En un <p>: el área y el grupo, en mayúsculas pequeñas espaciadas y con el color secundario. Si incluye un <code> con el nombre de un paquete, este conserva sus mayúsculas y minúsculas. En árabe se omite el espaciado entre letras |
.luz-doc-header | En un <p>: una frase en color secundario y con un tamaño mayor que el del texto |
.luz-doc-header | En un <ul>: las etiquetas. Cada <li> contiene una o dos palabras dentro de un contorno redondeado y mide al menos --luz-control-sm (28px) de alto. Los enlaces que contienen tienen la misma altura |
.luz-doc-header | En un <p>, en lugar de las etiquetas y solo en páginas que no sean de componentes: «Archivos:» y cada archivo dentro de un <code>, en una línea pequeña de color secundario |
Cómo funciona
CSS de components/doc-header.css de @luz-ds/catalog. Define el ritmo y los tamaños; las palabras las eliges tú.
- La cabecera es una cuadrícula de una columna. La separación entre las partes es
--luz-space-smy el espacio debajo de la cabecera es--luz-space-xl. - El
h1es un elemento sin clase dentro de la cabecera; esta le aplica estilos según su posición. - Las etiquetas enumeran los datos que alguien quiere saber antes de leer: qué archivos y scripts se usan, qué modos hay, si se ha probado y si se conocen problemas. Si una etiqueta lleva a otro sitio, es un enlace.
- Las palabras largas de las etiquetas se parten en lugar de ensanchar la página, de modo que las etiquetas se ajustan a 320px.
Sin JavaScript
No cambia nada. La cabecera contiene texto y enlaces; el paquete no incluye ningún script.
Teclado y ARIA
- Orden: el del código fuente: epígrafe, título, entradilla y, después, las etiquetas. Con Tab solo llegas a los enlaces de las etiquetas.
- Encabezados: el
h1es el únicoh1de la página. Un<header>dentro de<main>no es una zona de referencia de tipo banner. - Etiquetas: una lista de elementos sencillos que se anuncia como lista. Una etiqueta sin enlace es texto y no recibe el foco.
La pestaña Diseño incluye Contraste y foco.
Diseño
Cuándo usarlo
Usa la cabecera en la parte superior de todas las páginas de un sitio de documentación, para que el título y el tema de la página estén siempre en el mismo sitio.
- Una frase que explique qué permite hacer la página.
- Unas cuantas etiquetas con los datos que ayudan a decidir si seguir leyendo.
Cuándo no usarlo
No uses la cabecera para el banner del sitio: contiene el h1 de la página.
- Usa una sola cabecera por página. Una sección de una página larga lleva un
h2, no otra cabecera. - Para la cabecera de un artículo de blog, usa la cabecera de artículo de CMS.
- Una página de landing empieza con el hero.
Qué hacer y qué no
Cómo escribir el contenido
- Epígrafe: primero el área y después el grupo, separados por un espacio, un punto medio y otro espacio: «Guías · Configuración». Escribe en estilo de frase; el estilo aplica las mayúsculas.
- Título: el tema de la página o una tarea que empiece por un verbo: «Instala la herramienta de línea de comandos». Sin punto final.
- Entradilla: una frase de unas veinte palabras como máximo, que termine en punto.
- Etiquetas: entre dos y cinco, de una o pocas palabras. Indica un dato («Versión 2»), nunca un eslogan. «Sin problemas conocidos» enlaza a la lista.
Contraste y foco
Todo el texto aparece sobre la superficie de la página. El contorno de una etiqueta es decorativo: la palabra que contiene transmite el significado.
| Elemento | Color sobre fondo | Claro | Oscuro | Alto contraste | Mínimo |
|---|---|---|---|---|---|
Título | --luz-text-primary on --luz-surface-page | 15.8:1 | 15.1:1 | 21.0:1 | 4.5:1 |
Epígrafe | --luz-text-secondary on --luz-surface-page | 6.2:1 | 7.5:1 | 19.3:1 | 4.5:1 |
Entradilla | --luz-text-secondary on --luz-surface-page | 6.2:1 | 7.5:1 | 19.3:1 | 4.5:1 |
Etiqueta | --luz-text-secondary on --luz-surface-page | 6.2:1 | 7.5:1 | 19.3:1 | 4.5:1 |
Enlace en una etiqueta | --luz-brand-primary on --luz-surface-page | 5.6:1 | 7.7:1 | 14.1:1 | 4.5:1 |
Anillo de foco | --luz-focus-ring on --luz-surface-page | 5.6:1 | 7.7: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 enlaces de las etiquetas conservan el anillo de core, de 2 px,
--luz-focus-ring. - Área de activación: las etiquetas y los enlaces que contienen miden al menos 28 por 28 px, por encima del mínimo de 24 px de WCAG 2.2 (2.5.8).
- Bordes: el contorno de las etiquetas (
--luz-divider) es decorativo y no tiene un mínimo.
Tokens que usa
Los 12 tokens que leen las reglas de .luz-doc-header de components/doc-header.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-control-sm,--luz-space-sm,--luz-space-xs- Typography
--luz-font-sans,--luz-text-2xl,--luz-text-4xl,--luz-text-base,--luz-text-lg,--luz-text-xs- Radius
--luz-radius-full
La pestaña Código incluye Teclado y ARIA.