Índice lateral

Código

Copiar el marcado

import "@luz-ds/catalog/components/page-rail.css";

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/page-rail.min.css" integrity="sha384-rtBwzNTcuj/dbwc7iMTxhqi7LU16M2g06o5Y73z+/VADATrf1qbSJBM+Z2b3pNjq" crossorigin="anonymous">

El índice lateral como hijo directo de la estructura, entre la barra lateral y el contenido:

<aside class="luz-page-rail" aria-label="About this page">
  <div class="luz-page-rail__inner">
    <nav class="luz-page-rail__onpage" aria-labelledby="onpage-title">
      <details class="luz-page-rail__fold" open>
        <summary class="luz-page-rail__title" id="onpage-title">On this page</summary>
        <ul class="luz-page-rail__list">
          <li><a class="luz-sidebar__link luz-page-rail__link" href="#install">Install</a></li>
          <li><a class="luz-sidebar__link luz-page-rail__link" href="#configure">Configure</a>
            <ul class="luz-page-rail__sub">
              <li><a class="luz-sidebar__link luz-page-rail__link" href="#config-file">The config file</a></li>
            </ul>
          </li>
        </ul>
      </details>
    </nav>
    <div class="luz-page-rail__actions">
      <a href="https://example.com/docs/install.md">Copy page as Markdown</a>
      <a href="https://example.com/edit/install.md">Edit this page</a>
      <a href="https://example.com/issues/new">Report a problem</a>
    </div>
  </div>
</aside>

Variantes y opciones

No hay modificadores. El índice lateral es un <aside> que contiene una caja con dos bloques: la lista y las acciones.

Cómo funciona

CSS de components/page-rail.css de @luz-ds/catalog sobre el enlace de la barra lateral y su seguimiento del desplazamiento de catalog.

• Por debajo de 80rem, el índice lateral aparece encima del contenido, bajo la cabecera. A partir de 80rem ocupa una columna tan alta como el contenido, y su caja interior queda fija a --luz-page-rail-top desde la parte superior de la ventana: se detiene al final del índice y nunca tapa el pie. La caja interior no supera la altura de la ventana y se desplaza por sí sola si la lista es más larga.
• Los enlaces usan .luz-sidebar__link de catalog, así que su script marca la sección visible con aria-current="true". El índice lateral representa el enlace como texto de la página: la marca combina el grosor y un borde al principio, nunca depende solo del color.
• La lista incluye cada h2 de la página y, debajo, cada h3. No hay más niveles de anidación.
• «Copiar la página como Markdown» es un enlace al archivo Markdown de la página; te corresponde implementar su copia con un script. El índice lateral no se imprime.

Sin JavaScript

La lista y las acciones son enlaces, y el elemento <details> nativo funciona sin JavaScript. Ningún enlace aparece marcado como actual: esa marca la añade el script de catalog.

Teclado y ARIA

• Orden: el índice lateral aparece entre la barra lateral y el contenido en el código fuente, así que con Tab llegas a él antes que al texto: primero la lista y después las acciones. El enlace para saltar va al contenido, pasando por encima del índice.
• Teclas: pulsa Enter o Espacio en «En esta página» para plegar la lista. Con Tab llegas a cada enlace; con Enter vas a su sección.
• Nombres: el <aside> es una zona de referencia llamada «Acerca de esta página»; el <nav> recibe el nombre de su resumen: «En esta página».

La pestaña Diseño incluye Contraste y foco.

Diseño

Cuándo usarlo

Usa el índice lateral en páginas con varias secciones para que quien lee vea su estructura y pueda saltar a una de ellas.

• Una página con tres secciones o más, lo bastante larga como para desplazarse.
• Acciones propias de la página, no del sitio: editar, informar y copiar.

Cuándo no usarlo

No uses el índice lateral en una página corta: leer dos enlaces lleva más que leer la propia página.

• Incluye las secciones de una sola página. Las páginas del sitio van en la barra lateral.
• No anides más allá de un h3. Para mostrar el índice junto a un artículo, usa la tabla de contenidos de CMS.

Qué hacer y qué no

Cómo escribir el contenido

• Enlaces: el texto exacto del encabezado, breve y en estilo de frase.
• Título: «En esta página». Tradúcelo junto con el resto de la página.
• Acciones: empieza por el verbo, como en «Editar esta página» e «Informar de un problema». Mantén el orden: copiar, editar e informar.

Contraste y foco

La lista se muestra sobre la superficie de la página. El enlace bajo el cursor aparece sobre una superficie atenuada.

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 el resumen conservan el anillo de core, de 2 px, --luz-focus-ring.
• Marca: la sección visible se distingue por el grosor, un borde de 2px al principio y el color del texto.
• Área de activación: cada enlace, el resumen y cada acción miden al menos 28px de alto.

Tokens que usa

Los 14 tokens que leen las reglas de .luz-page-rail de components/page-rail.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.

Color

--luz-brand-primary, --luz-divider, --luz-surface-muted, --luz-text-primary, --luz-text-secondary

Spacing and sizing

--luz-control-sm, --luz-space-2xs, --luz-space-lg, --luz-space-md, --luz-space-sm, --luz-space-xl, --luz-space-xs

Typography

--luz-font-sans, --luz-text-sm

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