Cómo leer LUZ – Primeros pasos – Documentación de LUZ

Nombres de clase

El principio de un nombre de clase indica qué es y de qué paquete procede.

Qué significa cada prefijo de clase
Prefijo	Qué es	Paquete	Ejemplo
`.luz-`	Un componente o una parte de uno	core, catalog	`.luz-btn`, `.luz-hero`
`.o-`	Un objeto de maquetación: organiza elementos y no tiene aspecto propio	core	`.o-stack`
`.u-`	Una utilidad: una sola función, sin un componente alrededor	core	`.u-sr-only`
`.is-`	Un estado que un script refleja en un elemento. Puedes leerlo, pero no apliques estilos desde fuera: no forma parte de aquello en lo que puedes confiar	core	`.is-active`

Dentro de un componente, dos separadores indican cómo encajan sus partes. Un guion bajo doble nombra una parte del componente: .luz-card__title es el título de una tarjeta.

Un guion doble nombra una variante: .luz-btn--primary es el botón principal.

Lee este marcado de izquierda a derecha, una clase cada vez.

HTML

<div class="o-stack">
  <article class="luz-card">
    <h3 class="luz-card__title">Team plan</h3>
    <button class="luz-btn luz-btn--primary" type="button">Choose plan</button>
  </article>
</div>

o-stack es un objeto de maquetación: dispone sus elementos hijos en una columna.
luz-card es un componente, una tarjeta.
luz-card__title es una parte de la tarjeta: su título.
luz-btn es otro componente, un botón, y luz-btn--primary es su variante principal.

Nombres de tokens

Un token es una propiedad personalizada de CSS que empieza por --luz-. La palabra siguiente indica qué tipo de valor contiene.

Un token de cada tipo
Nombre	Tipo	Qué es
`--luz-blue-60`	Primitivo	Un color sin asignación: una familia y un nivel. No tiene una función y nunca cambia con el modo
`--luz-brand-primary`	Token semántico	Una función: el color de los enlaces y las acciones. Tiene un valor para cada modo
`--luz-space-md`	Paso de escala	Un paso de la escala de espaciado
`--luz-text-lg`	Paso de escala	Un paso de la escala tipográfica
`--luz-type-base`	Control	El valor a partir del cual se calcula una escala entera. Cámbialo para cambiar el tamaño de todos sus pasos
`--luz-z-modal`	Ajuste	Un valor que core usa para distribuir la página: orden de apilado y anchos de la maquetación

Los componentes de LUZ usan tokens semánticos y pasos de escala. Nunca usan un primitivo ni un control.
Puedes definir cualquier token en tu propio CSS. Hazlo tuyo explica cómo.

Cada familia tiene su página: color, tipografía, espaciado y tamaño, radio, sombras, movimiento y maquetación y puntos de ruptura.

Atributos

Las clases sirven para los estilos. Los atributos que empiezan por data- permiten que un script y tu marcado se comuniquen.

data-theme en <html> elige el modo de color (light, dark o high-contrast) o el nombre de un aspecto propio.
data-mode en <html> elige el modo de color dentro de un aspecto propio: data-theme="my-brand" con data-mode="dark".
data-luz-* son los puntos de integración de los scripts de LUZ, como data-luz-js, que el script establece en <html> cuando se ejecuta. Los scripts se conectan a estos atributos, nunca a una clase.
data-luz marca una zona para luz.conditional.css: el reinicio y los elementos sin clase se aplican solo dentro de ella.
data-luz-label-* sobrescribe un texto que escribe un script.

Estos son ejemplos, no la lista completa: la página de cada componente indica los atributos que usa.

Elementos que empiezan por luz

Una etiqueta que empieza por luz- es un elemento personalizado. Los de LUZ usan DOM ligero, así que tu CSS puede acceder a su interior, y sus partes son clases: .luz-<tag>__<part>.

Con script: <luz-search>, <luz-cookie-consent>, <luz-theme-mode>, <luz-theme-time> y <luz-timeline> necesitan su script para funcionar.
Solo CSS: <luz-lang-switch>, <luz-submenu> y <luz-announcement> no necesitan ningún script. Son etiquetas a las que puedes aplicar estilos con o sin script.

En Cómo se organiza LUZ se indica qué paquete contiene cada elemento.

Capas, en un párrafo

Todo el CSS de LUZ está en una capa de cascada llamada luz, que contiene capas con nombre, y cualquier CSS tuyo que no esté en una capa prevalece sobre todo sin necesidad de !important. Capas de cascada las enumera en orden y explica cómo sobrescribir una.

En qué puedes confiar

No todos los nombres son una promesa. Estas cuatro partes de LUZ son API pública: cualquier cambio se anuncia.

Tokens: todas las propiedades personalizadas --luz- de tokens.css, pero no las que un componente declara para sí mismo.
Clases: clases .luz-, .o- y .u- del marcado que muestra la documentación, con sus partes y variantes. No las clases .is-.
Atributos: data-theme, data-mode, data-luz-* y data-luz-label-*. No los atributos que usan los propios scripts del sitio de documentación.
Paquetes: el mapa exports de cada paquete y las rutas de los archivos que publica.

En la beta, cualquier cosa puede cambiar y el changeset de la versión explica cómo migrar. Consulta Qué es API pública, en VERSIONING.md en GitHub para ver la tabla completa.

Cómo leer el nombre de un archivo

El nombre de un archivo indica su contenido. Cada archivo CSS también tiene una versión .min con las mismas reglas minimizadas: luz.css y luz.min.css.

Archivos de la carpeta dist de cada paquete
Archivo	Paquete	Cuándo cargarlo
`luz-tokens.css`	`@luz-ds/tokens`	Siempre, salvo que uses tu propia fuente. Incluye los tokens y las reglas `@font-face` de ET Book
`tokens.css`	`@luz-ds/tokens`	En lugar de `luz-tokens.css`, si usas tu propia fuente: los mismos tokens, sin `@font-face`
`luz.css`	`@luz-ds/core`	Para cargar de una vez el restablecimiento, los elementos sin clases, los objetos de maquetación, los componentes y las utilidades
`base.css`	`@luz-ds/core`	Si solo quieres unos pocos componentes: carga el restablecimiento y los elementos sin clases y, después, un archivo por componente
`components/<name>.css`	`@luz-ds/core`	Después de `base.css`, para cada componente que uses
`luz.conditional.css`	`@luz-ds/core`	En lugar de `luz.css`, para una página que ya tiene diseño: el reinicio y los elementos sin clase se aplican solo dentro de `data-luz`. Los objetos, los componentes y las utilidades no están acotados
`themes/_template.css`	`@luz-ds/core`	Nunca lo uses tal cual: cópialo como punto de partida para crear tu propio aspecto
`components/<name>.css`	`@luz-ds/catalog`	Después de core, una por cada elemento del catálogo que use la página, como `<luz-search>`

Para elegir las líneas de tu compilación, elige tu fragmento.