# Cómo se organiza LUZ

Paquetes con dependencias en una sola dirección, CSS en capas de cascada dentro de una llamada luz y un script opcional.

### Límites entre paquetes

Cada paquete depende de los que aparecen por encima en esta lista, nunca de los que aparecen por debajo.

El nombre significa Light, Usable & Zero-dependency: ligero (CSS sin procesar y módulos ES, sin nada que compilar para quienes lo usan), usable por todo el mundo (HTML nativo, tres modos de color y pruebas de accesibilidad) y sin dependencias en tiempo de ejecución.

Package dependency chain
```text
@luz-ds/tokens   -> primitive and semantic tokens (standalone)
      ↓ required by
@luz-ds/core     -> components, objects, bare-element styles, optional JS
      ↓ required by
@luz-ds/catalog     -> search, cookie-consent, theme-time, lang-switch, submenu, announcement, and the patterns of a landing page, a blog or newspaper, a web application and a documentation site
```

- El catálogo necesita core y tokens; core necesita tokens; tokens no necesita nada.
- Tokens, core y catalog comparten versión. No hay paquetes para un tipo de sitio: los patrones de una landing page, un blog, una aplicación o un sitio de documentación son componentes del catálogo, un archivo cada uno.
- Los paquetes lo declaran como dependencias peer. Los scripts de core y catalog avisan en la consola si falta una capa.

La documentación sigue a los paquetes, con un área más: [Tipos de sitio](https://nandovejer.github.io/luz/es/docs/kinds/) reúne, para cada tipo, el prompt para un LLM y las recetas de sus partes, hechas con los paquetes de arriba y con los patrones de ese tipo en el catálogo.

### Qué necesita cada paquete

Busca la pieza que quieres y instala el paquete de su fila y los que aparecen debajo.

Qué paquete contiene cada parte de una página

- Modos de color, tokens semánticos, ET Book: `--luz-*`, `data-theme`: tokens: No hace falta nada más
- Restablecimiento y estilos de elementos HTML sin clases: `h1`, `p`, `a`, `ul`…: core: En `base.css` y `luz.css`
- Componentes: `.luz-btn`, `.luz-field`, `.luz-card`, `.luz-table`, `.luz-tabs`…: core: También hay un archivo por componente en `components/`
- Diálogo modal: `.luz-modal` en un `<dialog>`: core: El script es una alternativa para navegadores sin `command` y `commandfor`
- Objetos de maquetación: `.o-container`, `.o-grid`, `.o-stack`, `.o-media`: core: El espaciado procede de los tokens de espacio
- Maquetación de una aplicación con una columna lateral: `.o-shell`, `.o-main`: core: Un `<footer>` sencillo, como hijo directo de `.o-shell`, ocupa la parte inferior; su aspecto lo decides tú o lo define un tipo de sitio
- Una página sin barra lateral, una barra fija, un grupo de acciones: `.o-page`, `.o-sticky`, `.o-actions`: core: En lugar de `.o-shell`, para una página sin barra lateral: [la página y sus barras](https://nandovejer.github.io/luz/es/docs/components/layout/#objects-page)
- Modo de color: Automático, claro, oscuro y alto contraste: `<luz-theme-mode>`: core: `luz.js` carga su script, `theme-mode.js`, cuando la página contiene el elemento; sin él, los botones de opción siguen funcionando y Automático sigue al sistema: [Modo de color](https://nandovejer.github.io/luz/es/docs/components/theme-mode/)
- Enlace para saltar, banda y marco de imagen: `.luz-skip-link`, `.luz-band`, `.luz-image`: core: El marco de imagen mantiene una proporción y recorta la imagen; si no hay imagen, muestra una superficie lisa
- La cabecera, el hero, las secciones y el pie de una landing page: `.luz-site-header`, `.luz-hero`, `.luz-main`, `.luz-section`, `.luz-stat`, `.luz-site-footer`, `.luz-glow`: catalog: Un archivo cada uno, `components/<block>.css`. Se basa en los objetos de core (`.o-page`, `.o-sticky`, `.o-container`, `.o-grid--split`) y la navbar de catalog. Una cuadrícula de características usa `ul.o-grid.o-grid--split`, de core
- La cabecera, la cabecera de página y de artículo, el índice y el pie de un blog o periódico: `.luz-site-header` (`--publication`), `.luz-masthead`, `.luz-page-header`, `.luz-article-header`, `.luz-article`, `.luz-toc`, `.luz-site-footer`: catalog: Un archivo cada uno, `components/<block>.css`; el índice está en `article.css`. Se basa en los objetos de core y la navbar de catalog. Las tarjetas, los listados y la ficha del autor usan la tarjeta de core: consulta [Blog o periódico](https://nandovejer.github.io/luz/es/docs/kinds/blog/)
- La cabecera y el panel de control de una aplicación web: `.luz-app-bar` (`__product`, `__actions`, `__account`), `.luz-dashboard` (`__head`, `__title`, `__panel`): catalog: Un archivo cada uno, `components/app-bar.css` y `components/dashboard.css`. Se basa en la estructura, la barra fija, la cuadrícula y la tarjeta de core, y en la barra lateral de catalog. Sin script. Consulta [App header](https://nandovejer.github.io/luz/es/docs/catalog/app-bar/) y [Dashboard](https://nandovejer.github.io/luz/es/docs/catalog/dashboard/)
- La estructura, la cabecera de página, la barra lateral, el ejemplo, Qué hacer y qué no, la paginación y el pie de una web de documentación: `.luz-docs-layout`, `.luz-doc-header`, `.luz-page-rail`, `.luz-example`, `.luz-do-dont`, `.luz-pager`, `.luz-page-footer`: catalog: Un archivo cada uno, `components/<block>.css`. Se basa en la estructura, el bloque de código y las tablas de core, y en la barra lateral de catalog. Sin script. Consulta [Shell](https://nandovejer.github.io/luz/es/docs/catalog/docs-layout/)
- Los enlaces de una cabecera: `.luz-navbar`: catalog: Un archivo, `components/navbar.css`. Panel popover a 768 px o menos, que abre un `.luz-nav-toggle`, sin script. `luz.css` no lo incluye
- Una barra lateral, su marca y su botón de menú: `.luz-sidebar` (`__brand`, `__logo`, `__brand-name`, `__version`), `.luz-nav-toggle`: catalog: Un archivo, `components/sidebar.css`. El cajón es un popover nativo y no necesita script. `catalog.js` carga `sidebar.js`, el seguimiento del desplazamiento, cuando la página tiene una barra lateral; una página que solo carga core no lo tiene
- Un comando en un bloque enmarcado: `.luz-terminal`: catalog: Un archivo, `components/terminal.css`. Sin script propio: el botón de copia es de core
- Una línea de tiempo de eventos con fecha: `<luz-timeline>`, `.luz-timeline`: catalog: `catalog.js` carga su script, `timeline.js`, cuando la página contiene el elemento; sin él, la línea de tiempo es una lista
- Submenú y anuncio: `<luz-submenu>`, `<luz-announcement>`: catalog: Etiquetas sin script ni clase: el submenú es un `<details>` nativo entre los enlaces de una cabecera; el anuncio, una `<section>`
- Consentimiento de cookies: `<luz-cookie-consent>`, `.luz-cookie-consent`: catalog: `catalog.js` carga el script `cookie-consent.js` cuando la página contiene el elemento; muestra una banda fija en la parte inferior de la ventana; sin el script permanece oculta
- Modo de color con la hora del día y deslizador del día: `<luz-theme-time>`: catalog: `catalog.js` carga el script `theme-time.js` cuando la página contiene el elemento, y `theme-time-bar.js` si tiene un `variant="bar"`; sin ellos, los botones de opción de core siguen funcionando y el modo automático sigue al sistema
- Selector de idioma: `<luz-lang-switch>`: catalog: Sin script
- Búsqueda del sitio: `<luz-search>`, `.luz-search`: catalog: Necesita el script (`catalog.js`, que carga `search.js` cuando la página contiene el elemento) y un archivo de índice; sin ellos, es un enlace
- Estilos de impresión: No hay que añadir nada: core: En `luz.css`; el catálogo añade sus propias reglas de impresión
- Una zona en una página que ya tiene diseño: `data-luz`: core: `luz.conditional.css`, en lugar de `luz.css`
- Comprobación de lo que has escrito tú o un agente de IA: `npx @luz-ds/check@0.3.0`, el comando `luz-check`: check: Una herramienta sin CSS ni capa, que no necesita ningún otro paquete: analiza tu HTML y CSS sin conexión. Consulta [Trabajar con IA](https://nandovejer.github.io/luz/es/docs/get-started/ai/)

- **Dos formas de maquetar una página, ambas de core.** `.o-shell` con `.o-main`: una columna lateral junto al área principal. `.o-page`: cabecera, contenido y pie en una columna. Elige una para la estructura de la página: la primera si tiene barra lateral y la segunda si no. Las cabeceras y los pies de landing o CMS funcionan con ambas; esta documentación usa `.o-shell`.
- El catálogo necesita core, y core necesita tokens, así que cada paquete necesita también todos los paquetes de debajo. Los patrones de una landing page, un blog, una app y una web de documentación son componentes de catalog, así que también necesitan core y tokens.

### Capas CSS

El CSS de core usa capas de cascada nativas (`@layer`), en el orden ITCSS y dentro de una capa contenedora llamada `luz`. Las seis de abajo contienen sus reglas; [la página sobre capas](https://nandovejer.github.io/luz/es/docs/get-started/layers/) las enumera todas, junto con tokens, catálogo e impresión.

Una capa posterior prevalece sobre una anterior, y cualquier CSS tuyo que no esté en una capa prevalece sobre todo LUZ, sin `!important`. [Cómo ordenarlas y sobrescribirlas](https://nandovejer.github.io/luz/es/docs/get-started/layers/).

Core cascade layers
```text
packages/core/src/
  settings/_settings.css      luz.settings    z-index, layout widths, field text
  generic/_reset.css          luz.generic     the reset
  elements/*.css              luz.elements    bare HTML elements, zero specificity
  objects/_objects.css        luz.objects     layout: .o-*
  components/*.css            luz.components  the components: .luz-*
  utilities/_utilities.css    luz.utilities   single-purpose helpers: .u-*
```

- La capa de componentes contiene 29 componentes.
- `dist/luz.css` contiene estas seis capas y `luz.print`. Tokens está en `luz.tokens`, catalog, con la barra de navegación, la barra lateral, el terminal, la línea de tiempo y los patrones de un tipo de sitio, en `luz.catalog`; `luz.themes` está vacía, reservada para un tema propio. Si una página solo necesita unos pocos componentes, carga `dist/base.css` (ajustes, restablecimiento y elementos) y luego `dist/components/<name>.css` para cada uno.
- Las reglas de los elementos sin clase están dentro de `:where()`, así que cualquier clase prevalece sobre ellas.

### El script

Un único punto de entrada opcional, `luz.js`, inicia todos los comportamientos de la página: modo de color, botones para copiar, diálogos, resaltado, reproductores y pestañas.

Load the core script
```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@luz-ds/core@0.3.0/dist/luz.min.js"></script>
```

Para cargar menos código, importa un módulo y llama a su función `init`. Consulta [Módulos de JavaScript](https://nandovejer.github.io/luz/es/docs/get-started/javascript/).

### Página mínima

Minimal page skeleton
```html
<!doctype html>
<html lang="en" data-theme="light">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Sign up – Acme</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/tokens@0.3.0/dist/luz-tokens.min.css">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/core@0.3.0/dist/luz.min.css">
</head>
<body>
  <main class="o-container">
    <h1>Sign up</h1>
    <form action="/signup/" method="post">
      <div class="luz-field">
        <label class="luz-field__label" for="email">Email</label>
        <input class="luz-input" id="email" name="email" type="email" autocomplete="email" required>
      </div>
      <button class="luz-btn luz-btn--primary" type="submit">Create account</button>
    </form>
  </main>
</body>
</html>
```