Armazón de página

Código

Copiar el marcado

import "@luz-ds/catalog/components/docs-layout.css";

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/docs-layout.min.css" integrity="sha384-4mL+wj5xGmF98hYy2houcLGyUl4xNNTemLvMbtsCj1A7wpQ7RE3Ng26GboK9hgm9" crossorigin="anonymous">

La estructura en <body>, seguida de la cabecera, la barra lateral, el índice lateral, el contenido y el pie, en el orden en que se recorren con el teclado. El enlace para saltar al contenido lo lleva hasta él, más allá de la barra lateral y del índice:

<body class="o-shell luz-docs-layout">
  <a class="luz-skip-link" href="#main-content">Skip to content</a>
  <header>
    <button class="luz-nav-toggle" type="button" popovertarget="docs-nav" aria-label="Menu">…</button>
    <p><a href="/">Acme docs</a></p>
  </header>
  <nav class="luz-sidebar luz-docs-nav" id="docs-nav" aria-label="Acme docs" popover>…</nav>
  <aside class="luz-page-rail" aria-label="About this page">…</aside>
  <main class="o-main luz-docs-main" id="main-content" tabindex="-1">
    <header class="luz-doc-header">…</header>
    …
  </main>
  <footer>…</footer>
</body>

Variantes y opciones

Sin modificadores. Tres clases en elementos nativos y tres propiedades personalizadas.

Cómo funciona

CSS de components/docs-layout.css de @luz-ds/catalog sobre la estructura de core y la barra lateral de catalog. Docs define las columnas y el ancho de lectura; core aporta la cuadrícula y la barra lateral, el cajón.

• A partir de 80rem hay tres columnas: barra lateral, contenido e índice lateral. A partir de 60rem hay dos, y el índice lateral se muestra encima del contenido. Por debajo, hay una, en el orden del marcado: barra lateral, índice lateral, contenido y pie.
• Un <header> sin estilos ocupa todas las columnas. El pie queda debajo del contenido y la barra lateral se extiende a su lado.
• Entre 769px y 60rem, la barra lateral es el primer bloque, por encima del contenido. A 768px o menos, pasa a ser el cajón de la barra lateral: un popover que abre el botón de menú.
• Todos los elementos del contenido respetan --luz-docs-measure, así que un ejemplo tiene el ancho de una línea de texto. Al imprimir, se omite el índice lateral.

Sin JavaScript

No cambia nada: la maquetación está hecha con CSS. El cajón es un popover que abre el atributo popovertarget del botón de menú, sin necesidad de scripts.

En un navegador sin la API de popover, la barra lateral permanece en la página, por encima del contenido.

Teclado y ARIA

• Orden: el del código fuente; la cuadrícula no lo cambia. Enlace para saltar al contenido, cabecera, barra lateral, índice lateral, contenido y pie. El enlace lleva al contenido, más allá de la barra lateral y del índice.
• Enlace para saltar al contenido: coloca primero el enlace para saltar al contenido, dirigido a <main>, para que quien use el teclado pueda omitir la barra lateral.
• Regiones: un <header> hijo de <body> es el banner; nombra el <nav> con el nombre del sitio y el <aside> «Acerca de esta página».
• Teclas: pulsa Enter o Espacio en el botón de menú para abrir el cajón; Esc para cerrarlo. El navegador se encarga.

La pestaña Diseño incluye el contraste y el foco.

Diseño

Cuándo usarlo

Usa esta estructura para las páginas de un sitio de documentación: se leen una tras otra, con una barra lateral que las reúne y una lista de las secciones de cada página.

• Tu sitio tiene más páginas de las que caben en una cabecera.
• Quienes leen recorren las páginas en orden.

Cuándo no usarlo

No uses esta estructura para una página que no sea de documentación: presupone que hay una barra lateral y una columna de contenido.

• Para una página sin barra lateral, usa .o-page de core: consulta la página y sus bandas.
• Para una aplicación web, usa App; para un blog, CMS.

Qué hacer y qué no

<nav class="luz-sidebar luz-docs-nav">…</nav>
<aside class="luz-page-rail">…</aside>
<main class="o-main luz-docs-main">…</main>

<nav class="luz-sidebar luz-docs-nav">…</nav>
<main class="o-main luz-docs-main">…</main>
<aside class="luz-page-rail">…</aside>

Cómo escribir el contenido

La estructura apenas incluye texto propio, y cada texto es un nombre.

• Enlace para saltar al contenido: «Saltar al contenido».
• Barra lateral: usa aria-label con el nombre de la documentación, por ejemplo, «Documentación de Acme». No uses «Navegación»: el rol ya lo indica.
• Índice lateral: «Acerca de esta página». Su lista se llama «En esta página».
• Enlaces de la barra lateral: los títulos de las páginas, en el orden en que se recorren.
• Botón de menú: «Menú».

Contraste y foco

La estructura no define sus propios colores. El texto se muestra sobre la superficie de la página y la barra lateral conserva sus propios colores.

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: todos los enlaces y botones conservan el anillo de core, de 2 px, definido por --luz-focus-ring.
• Adaptación: a 320px la página tiene una sola columna y no se desplaza en horizontal. Las pruebas lo comprueban.

Tokens que usa

Los 4 tokens que usan las reglas de .luz-docs-layout en components/docs-layout.css del catálogo, agrupados por familia. Cada familia enlaza a su página, donde se muestran los valores de todos los modos. En Figma son variables con los mismos nombres: consulta Tokens en Figma.

Spacing and sizing

--luz-space-3xl, --luz-space-lg, --luz-space-md, --luz-space-xl

La pestaña Código incluye teclado y ARIA.