Primeros pasos

Instala LUZ

Esta traducción la ha escrito una IA y todavía no la ha revisado ninguna persona. Leer esta página en inglés

Elige un nivel y copia un comando de instalación o las etiquetas de CDN. Cada nivel necesita los que están por debajo, pero ninguno de los que están por encima.

LUZ es un punto de partida, no un sitio terminado. El contenido, la marca y las decisiones finales son tuyos: revisa el resultado antes de publicar.

¿Ya sabes qué estás creando? Elige tu fragmento y copia las líneas que necesitas, con los hashes de CDN incluidos.

Cargar LUZ desde un CDN envía las direcciones IP de tus visitantes al CDN. Si no quieres que ocurra, instala desde npm y sirve los archivos desde tu propio servidor.

Beta

Los nombres, las clases y el comportamiento aún pueden cambiar antes de la versión estable. Fija una versión exacta y lee el registro de cambios antes de actualizar.

¿Qué nivel necesito?

Un proyecto nuevo: nivel 2, tokens y core. luz.css da estilo al HTML que escribes.
Un proyecto que ya tiene diseño: para empezar, nivel 1, solo tokens: no cambia nada de lo que se ve. Después, el nivel 2 para un proyecto existente, con luz.conditional.css, una región cada vez. Migra un proyecto a LUZ tiene los pasos.
Tus propios componentes, los colores y el espaciado de LUZ: nivel 1, solo tokens.
Botones, formularios, tablas y diálogos listos para usar: nivel 2, tokens y core.
Páginas completas: estructura, cabecera, pie de página y búsqueda: nivel 3, el Catálogo, los tres paquetes.
Una landing page, con su cabecera, hero y bloques: nivel 3 y los patrones para ese tipo de sitio, que son componentes del catálogo.

Nivel 1: solo tokens

Propiedades personalizadas de CSS: las escalas de color, espacio y tipografía, los roles tipográficos, los puntos de ruptura y las duraciones del movimiento, y los colores de los modos claro, oscuro y de alto contraste. No necesitas ningún otro paquete de LUZ.


            $
            pnpm add @luz-ds/tokens

HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/tokens@0.3.0/dist/luz-tokens.min.css">

Con un bundler como Vite, importa los archivos en lugar de añadir etiquetas. Un href no puede indicar un paquete: estas rutas solo sirven para import.

Bundler

import "@luz-ds/tokens/css";

El texto corrido y los encabezados usan ET Book, una fuente con licencia MIT que se incluye con los tokens. Los controles, las etiquetas y las tablas usan la sans del sistema, y el código, la mono del sistema.
¿Vas a usar tus propias fuentes? Carga dist/tokens.min.css: contiene los mismos tokens, pero sin reglas @font-face.
Comprueba que tus colores cumplen las proporciones de WCAG con npx @luz-ds/tokens@0.3.0 check-contrast o en el navegador.

Nivel 2: tokens y core

Los 29 componentes, los estilos de los elementos HTML sin clases y JavaScript opcional. Carga primero los tokens.


            $
            pnpm add @luz-ds/tokens @luz-ds/core

HTML

<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">

<!-- Optional: copy buttons, tabs, players, the color mode -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@luz-ds/core@0.3.0/dist/luz.min.js"></script>

Bundler

import "@luz-ds/tokens/css";
import "@luz-ds/core/css";

// Optional: copy buttons, tabs, players, the color mode
import "@luz-ds/core";

Todas las páginas funcionan sin el script. Consulta qué aporta cada módulo de JavaScript.
¿Solo necesitas un componente? Carga dist/base.min.css y el archivo que quieras, por ejemplo dist/components/button.min.css.
¿Tienes marcado al que no puedes añadir clases, como Markdown o el de un CMS? Un button, un campo o una table sin clase ya tienen su aspecto en luz.css. En una página que ya tiene diseño, carga en su lugar luz.conditional.css y marca la zona con data-luz.

Nivel 2 para un proyecto que ya tiene diseño

Carga luz.conditional.css en lugar de luz.css. Es el mismo archivo, con el reset y los elementos sin clase limitados a la región que marcas con data-luz. Carga primero los tokens, como en cualquier nivel. Desde un CDN, enlaza luz.conditional.min.css de @luz-ds/core en lugar de luz.min.css; con un bundler, impórtalo como se muestra abajo.

Bundler

import "@luz-ds/tokens/css";
import "@luz-ds/core/conditional.css";

El elemento con data-luz toma la fuente, el color y el fondo de la página. Los tokens siguen en :root.
Los objetos de maquetación, los componentes y las utilidades no se limitan a la región: se aplican allí donde pongas su clase.
Tu CSS antiguo no debe quedar sin capa, o ganará a LUZ. Ponlo en una capa anterior a luz: mira Capas de cascada y Migra un proyecto a LUZ.

Nivel 3, el Catálogo: tokens, core y catalog

La navegación del sitio y las piezas con un script o una identidad propios: barra de navegación, barra lateral, terminal, línea de tiempo, búsqueda, consentimiento de cookies, modo de color según la hora del día, selector de idioma, submenú, anuncio y preguntas frecuentes, y los patrones de un tipo de sitio. El catálogo necesita core y tokens.

La estructura de la página de cada tipo de sitio, desde la cabecera hasta el pie, también está en el catálogo, una hoja de estilos por patrón: consulta Tipos de sitio.

El catálogo tiene una hoja de estilos por componente: enlaza las que use la página, después de core.


            $
            pnpm add @luz-ds/tokens @luz-ds/core @luz-ds/catalog

HTML

<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">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/search.min.css">

<!-- Optional: core behaviours, and the site search and cookie banner -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@luz-ds/core@0.3.0/dist/luz.min.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/catalog.min.js"></script>

Bundler

import "@luz-ds/tokens/css";
import "@luz-ds/core/css";
import "@luz-ds/catalog/components/search.css";

// Optional: core behaviours, and the site search
import "@luz-ds/core";
import "@luz-ds/catalog";

Tipos de sitio

Para empezar una landing page, un blog, una app o un sitio de documentación, ve a Tipos de sitio: un prompt para cualquier LLM y las recetas de cada parte para copiar.

No hay un paquete para cada tipo de sitio. Sus patrones son componentes del catálogo, una hoja de estilos cada uno, con el nombre de lo que es la pieza, <block>.css. Instala el nivel 3 y enlaza, después de core, los archivos que use tu página:

Landing page: site-header, hero, main, section, stat, site-footer y glow: la cabecera, el hero, las secciones y el pie de página.
Blog o periódico, con cualquier CMS: site-header (o masthead para un periódico), page-header, article-header, article, post-list y site-footer: la cabecera, la cabecera de página y de artículo, el índice, la lista de artículos y el pie.
Aplicación web: app-bar, dashboard y, para los paneles que muestran datos, bar-list, column-chart, stacked-bar, ring y heat-map.
Sitio de documentación: docs-layout, doc-header, page-rail, example, do-dont, pager y page-footer.

El catálogo tiene una página para cada patrón e indica a qué tipos de sitio les encaja mejor.

HTML

<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">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/site-header.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/hero.min.css">

Bundler

import "@luz-ds/tokens/css";
import "@luz-ds/core/css";
import "@luz-ds/catalog/components/site-header.css";
import "@luz-ds/catalog/components/hero.css";

Enlaza los archivos de un tipo en el orden de la lista de arriba.
Enlaza hero junto con section: el encabezado de una sección comparte sus reglas con el hero.
Ninguno tiene un script. El de catalog es opcional: con el índice de un blog, marca la sección visible; con la barra lateral de una app, marca el enlace actual y cierra el panel al seguir un enlace. El de core no lo hace.

Antes de publicar

npm y pnpm instalan automáticamente los niveles inferiores. Yarn solo muestra un aviso, así que indica todos los paquetes, como arriba.
En un CDN, fija una versión exacta y añade un hash integrity con crossorigin="anonymous". Calcula el hash a partir del archivo que cargas, como se muestra abajo.
Los scripts de core y catalog muestran un aviso en la consola si falta el nivel inferior.
Establece lang en <html>: los scripts de core escriben sus textos en ese idioma (se incluyen inglés y español).

Shell

curl -s https://cdn.jsdelivr.net/npm/@luz-ds/core@0.3.0/dist/luz.min.css | openssl dgst -sha384 -binary | openssl base64 -A

Añade el resultado como integrity="sha384-…" a la etiqueta que carga ese archivo y repite el proceso con cada archivo.

El hash de un script solo cubre ese archivo, no los que carga después. catalog.min.js carga search.min.js en páginas con búsqueda, cookie-consent.min.js en páginas con un banner de cookies y theme-time.min.js en páginas con la hora del día para el modo de color.

Asigna a cada uno su propio hash en un mapa de importaciones, antes del primer script de módulo. Funciona en Chrome 127, Safari 18 y Firefox 138 y posteriores; un navegador más antiguo lo ignora y carga los archivos sin comprobarlos.

Un <link rel="modulepreload"> con un hash no protege en Safari ni en Firefox: úsalo solo como indicación para mejorar el rendimiento.

HTML

<script type="importmap">
{
  "integrity": {
    "https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/search.min.js": "sha384-…",
    "https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/cookie-consent.min.js": "sha384-…",
    "https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/theme-time.min.js": "sha384-…"
  }
}
</script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/catalog.min.js" integrity="sha384-…" crossorigin="anonymous"></script>

Siguientes pasos

Elige tu fragmento para tu tipo de sitio y la forma de cargarlo.
Explora los componentes y copia su marcado.
Configura los modos de color: claro, oscuro y de alto contraste.
Aprende cómo funcionan los tokens antes de escribir tus propios componentes.
Descubre cómo se organiza LUZ: paquetes, capas de CSS y estructura de la página.

Preguntas frecuentes

Las respuestas breves. Cada una enlaza a la página que la explica.

¿Qué es LUZ?

LUZ es un sistema de diseño para la web, en tres paquetes: tokens (colores, escalas, fuentes y tres modos de color), core (el reset, el estilo de los elementos HTML, los objetos de maquetación, los componentes y JavaScript opcional) y el catálogo (piezas que actúan para todo el sitio, como la búsqueda). Usa solo los tokens, core con los tokens, o los tres. Trabajar con IA muestra cómo una IA puede escribir un sitio con LUZ.

¿Tienen estilo las etiquetas HTML sin clase?

Sí, la mayoría. El texto, los enlaces, las listas, las tablas, los botones, los campos de formulario, details y dialog salen con estilo sin ninguna clase. Las etiquetas que solo estructuran la página, como div, section, header y nav, no tienen estilo: la maquetación es tuya. Qué elementos tienen estilo sin clase los enumera todos.

¿Para qué sirven las clases?

Una clase añade lo que el HTML no puede decir: un enlace que parece un botón, un papel como peligro, un tamaño, un componente con su propio marcado, como una tarjeta, y la maquetación con los objetos o-*. El HTML dice el resto: type="button" hace el botón secundario, y aria-invalid="true" marca un campo con error. Explora los componentes para ver qué añade cada clase.

¿Necesito JavaScript?

No. La mayoría de los componentes son solo CSS, y los que tienen un script funcionan también sin él. Módulos de JavaScript dice qué añade cada módulo.

¿Puedo cambiar los estilos por defecto?

Sí, sin pelearte con ellos. Cambia los tokens para cambiar todo el aspecto, o escribe tu propio CSS: el CSS sin capa gana a todas las capas de LUZ, sin !important. Lo que no tocas se queda. Cambiar los estilos por defecto muestra las tres formas.

¿LUZ es solo para proyectos nuevos?

No. LUZ encaja mejor en un proyecto nuevo, pero puedes añadirlo a uno que ya tiene diseño, una región cada vez: carga luz.conditional.css en lugar de luz.css y pon data-luz en la región. Nivel 2 para un proyecto que ya tiene diseño tiene las líneas que debes cargar.

¿Cómo migro un proyecto a LUZ?

Migra una página cada vez, en cinco pasos: los tokens con tu marca, el CSS antiguo en una capa anterior a LUZ, una primera región, las demás páginas una a una, y el CSS antiguo fuera. Una IA hace el trabajo mecánico; tú decides y compruebas. Migra un proyecto a LUZ tiene los pasos.