Con un empaquetador o framework

Los imports

Importa el CSS de cada paquete que uses, primero tokens, y el script si quieres añadir comportamiento. Un empaquetador resuelve estos nombres desde node_modules; un <link> en HTML no puede hacerlo.

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

// Only if the page uses a catalog element: one import each (here the search)
import "@luz-ds/catalog/components/search.css";
import "@luz-ds/catalog";

// A pattern of a kind of site is a catalog component too: one import each (here the hero of a landing page)
import "@luz-ds/catalog/components/hero.css";

• Primero van los tokens: todos los demás paquetes los necesitan.
• La barra de navegación, la barra lateral, el terminal y la línea de tiempo son componentes de catalog: @luz-ds/core/css no los incluye, así que importa @luz-ds/catalog/components/<name>.css de cada uno que uses.
• import "@luz-ds/core" es el script. Es opcional: todas las páginas de LUZ funcionan sin él.
• Para cargar menos CSS, importa @luz-ds/core/base.css y después un archivo por componente, por ejemplo @luz-ds/core/components/button.css.
• Para cargar un módulo de script, impórtalo por su nombre y llama a su función: consulta Módulos de JavaScript.

Para ver las líneas adecuadas a lo que estás creando, con las etiquetas CDN y sus hashes de integridad, elige tu fragmento.

Cada nombre anterior es una entrada del mapa exports de su paquete. Esta tabla los enumera todos.

El orden de las capas se conserva al empaquetar

Todos los archivos CSS que publica LUZ empiezan con la misma declaración @layer, que define el orden de todas sus capas. Así, el orden se mantiene aunque tu herramienta divida, reordene o una los archivos: el primer archivo que se carga lo establece.

En la compilación de Astro que aparece a continuación, las capas quedaron en el orden declarado, primero luz.tokens y al final luz.print; una regla del consumidor sin capa quedó la última.

Tu CSS que esté fuera de cualquier capa prevalece sobre todas las capas de LUZ, esté donde esté, sin necesidad de !important. Capas de cascada contiene la lista completa y explica cómo sobrescribir una.

Astro, paso a paso

Un proyecto nuevo de Astro con los tokens y core de LUZ, una plantilla que los carga y CSS propio que se aplica al final.

Creado con Astro 7.3 el 2026-10-15. LUZ está en beta y Astro cambia entre versiones, así que esta página tiene fecha: si algún paso falla con una versión más reciente de Astro, consulta primero sus notas de esa versión.

Para la compilación se usaron paquetes creados desde el repositorio de LUZ en la versión 0.0.0, instalados con npm install --legacy-peer-deps, porque los rangos de dependencias peer ^0.1.0 no se resuelven hasta que se publique la versión 0.1.0. Después, el comando siguiente no necesita ninguna opción.

El proyecto

my-site/
├─ package.json
├─ astro.config.mjs            (empty config: defineConfig({}))
└─ src/
   ├─ layouts/Base.astro       the two CSS imports, the script
   ├─ styles/site.css          your own CSS, last, outside any layer
   └─ pages/index.astro

astro.config.mjs se deja tal y como lo crea Astro. LUZ no necesita ninguna configuración en él.

Los comandos

npm create astro@latest my-site
cd my-site
npm install @luz-ds/tokens @luz-ds/core
npm run dev

La plantilla

---
// src/layouts/Base.astro
import "@luz-ds/tokens/css";
import "@luz-ds/core/css";
import "../styles/site.css";
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My site</title>
  </head>
  <body>
    <slot />
    <script>
      import "@luz-ds/core";
    </script>
  </body>
</html>

Tu CSS y la página

/* src/styles/site.css */
:root { --luz-type-base: 1.125rem; }

---
// src/pages/index.astro
import Base from "../layouts/Base.astro";
---
<Base>
  <main class="o-container">
    <h1>My site</h1>
    <button class="luz-btn luz-btn--primary" type="button">Save changes</button>
  </main>
</Base>

La regla de site.css establece el control tipográfico en 1.125rem y prevalece sobre el valor predeterminado de LUZ, sin capa y sin !important. Hazlo tuyo explica los demás controles.

Qué mostró la compilación

• astro build y astro dev funcionaron con los dos imports CSS en el encabezado de una plantilla y sin configuración en astro.config.mjs.
• Astro agrupó <script> con import "@luz-ds/core" en un único archivo de módulo y separó los fragmentos de carga diferida.
• Las fuentes se generaron como archivos con hash, y las capas y tu propia regla quedaron en el orden descrito arriba.

Se examinó el resultado de la compilación, pero no se abrió la página generada en un navegador. No se probó Astro con un enrutador de transiciones de vista (<ClientRouter />) ni Windows.

El import de un patrón de un tipo de sitio tiene la misma estructura que el de la búsqueda de arriba, pero no se compiló.

Vite, Next, Nuxt y SvelteKit

Para esta página solo se compiló Astro; Vite por sí solo, Next, Nuxt y SvelteKit no se compilaron ni probaron. Los imports son los mismos y van en la plantilla raíz o en el archivo de entrada de la aplicación.

La documentación de cada herramienta indica dónde colocar el CSS de un paquete:

• Documentación de Vite
• Documentación de Next.js
• Documentación de Nuxt
• Documentación de SvelteKit

Hay algo que todas comparten. Un módulo de LUZ no produce efectos secundarios al importarlo hasta que llamas a su función init, y luz.js y catalog.js comprueban primero que exista document.

Por eso, los frameworks que renderizan en el servidor pueden importarlos. En Node sin document se importaron diez módulos de core y catalog sin errores.

Fuentes y recursos

@luz-ds/tokens/css es luz-tokens.css, y sus reglas @font-face apuntan a los archivos de ET Book con url(). El empaquetador resuelve esas rutas: Astro generó los archivos como recursos woff2 con hash.

Para no usar ET Book, importa @luz-ds/tokens/tokens.css. Incluye los mismos tokens y no tiene reglas @font-face, así que no se descarga ninguna fuente.

Después, define --luz-font-body con la fuente que uses: Hazlo tuyo explica cómo.

Una CDN en un framework

Puedes cargar LUZ desde una CDN en la plantilla de un framework en lugar de importarlo. En una plantilla de Astro, el <link rel="stylesheet"> en <head> y el <script type="module" src="https://…">, cada uno con integrity y crossorigin, se quedan tal cual.

Lo mismo ocurre con un script con is:inline. Astro solo procesa un <script> que no tenga ningún atributo aparte de src.

Usa la CDN o los imports, pero no ambos: LUZ se cargaría dos veces. Elige tu fragmento incluye las etiquetas y sus hashes.

Si algo no funciona

• Un aviso sobre una dependencia peer. @luz-ds/core requiere @luz-ds/tokens en la versión ^0.1.0 || ^0.2.0 || ^0.3.0 || ^0.4.0. Instala ambos en la misma versión: npm install @luz-ds/tokens @luz-ds/core.
• La herramienta no puede resolver @luz-ds/core/css. La exportación es ./css, sin extensión de archivo. Si la herramienta indica que un import no se puede resolver, añade el paquete a vite.ssr.noExternal, como se explica en la guía de estilos de Astro.
• Los estilos aparecen en el orden equivocado. Dos copias de LUZ en la página, por ejemplo una de una CDN y otra del empaquetador, ponen sus reglas en las mismas capas: cárgalo una sola vez. Un @import con layer(luz) anida los nombres como luz.luz.components: quita layer(). Capas de cascada explica el orden.

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  vite: { ssr: { noExternal: ["@luz-ds/tokens", "@luz-ds/core"] } },
});