Capas de cascada

Declara primero el orden

Todo el CSS de LUZ está dentro de una capa de cascada, luz. Colócala entre tu restablecimiento y tus propios estilos, y declara ese orden antes de cargar ninguna hoja de estilos.

@layer reset, luz, app;

• El orden de las capas depende de la primera aparición de sus nombres. Una declaración como esta, antes que todo lo demás, lo fija.
• En HTML, ponla en un <style> antes de los elementos <link>. En una hoja de estilos, ponla en la primera línea, antes de cualquier @import de LUZ.
• Una capa posterior prevalece sobre una anterior. Así que app prevalece sobre luz, y luz sobre reset.
• No tienes que usar estos nombres. Usa las capas que quieras: luz es el único nombre que añade LUZ.

Las capas y los nombres con punto, como luz.components, funcionan en todos los navegadores actuales y están disponibles desde marzo de 2022 (MDN).

Qué contiene luz

Tokens, core y catalog ponen sus reglas en capas propias dentro de luz. Se muestran aquí de la primera a la última: una capa más abajo en la tabla prevalece sobre las de arriba.

Los patrones de un tipo de sitio tenían cada uno su capa: luz.landing, luz.cms, luz.app y luz.docs. Esas capas ya no existen, porque sus patrones son componentes de catalog. Si tu propia declaración @layer nombra alguna, quítala.

Cada archivo que publica LUZ repite primero el orden de esta lista, así que es el mismo sea cual sea el archivo que cargue primero la página. Estos nombres son públicos: cambiar uno es un cambio incompatible.

El CSS sin capa prevalece

Los estilos que no están en ninguna capa prevalecen sobre todas las capas, sea cual sea el orden en el código fuente. Así que una regla normal tuya prevalece sobre luz y también sobre tu propia capa app.

• Si tu CSS no usa capas, nada cambia: ya prevalece sobre LUZ sin necesidad de !important.
• Si usas capas, mantén tus reglas dentro de una: una regla sin capa que olvides incluir sobrescribirá tus propias capas.
• El orden de capas no ayuda con las reglas que están fuera de ellas. Pon la sobrescritura en app o sin capa, y ten claro cuál has elegido.

Sobrescribir LUZ

Tres formas de sobrescribir estilos, empezando por la más sencilla. Todas prevalecen sobre LUZ porque app va después de luz.

@layer reset, luz, app;

@layer app {
  /* A token: every component that reads it follows */
  :root {
    --luz-brand-fill: #0b5a8c;
  }

  /* A component: your rule, in your layer */
  .luz-btn {
    min-height: 3rem;
  }

  /* A catalog component */
  luz-announcement {
    font-size: 1rem;
  }
}

• Prioriza los tokens. Un token modifica todos los componentes que lo usan, en el modo en el que se define. Comprueba los colores que establezcas con la comprobación de contraste.
• No necesitas !important ni selectores más largos: el orden de las capas prevalece primero, y la especificidad solo cuenta dentro de una misma capa.
• Mantén las sobrescrituras de color en el modo correcto: :root en app también prevalece sobre el modo oscuro de LUZ. Define el token para cada modo, por ejemplo en [data-theme="dark"].

Por qué hay una sola capa contenedora

Antes, las capas de LUZ eran seis nombres de nivel superior: settings, generic, elements, objects, components y utilities. Son breves y comunes, y otras herramientas usan algunos de esos nombres.

Una página que cargaba una de ellas junto con LUZ mezclaba sus capas components o utilities con las de LUZ, y el orden entre ellas dependía del azar.

• Dentro de luz, los nombres de capa de LUZ nunca coinciden con los tuyos.
• Un solo nombre ordena todo LUZ: colocas luz una vez y no tienes que saber qué contiene.
• Funciona con un <link> o desde una CDN, donde no se puede añadir una capa desde fuera.

Aun así, puedes poner una capa tuya entre dos capas de LUZ si las nombras en la primera declaración: @layer luz.components, mine, luz.utilities;.

Cargar con @import

Con un empaquetador que resuelva nombres de paquetes, o con rutas a los archivos, cárgalos tal cual. No añadas layer(luz) al import: los archivos ya declaran sus capas dentro de luz y envolverlos anidaría los nombres como luz.luz.components.

@layer reset, luz, app;

@import url("@luz-ds/tokens/css");
@import url("@luz-ds/core/css");
@import url("@luz-ds/catalog/components/search.css"); /* one per catalog component the page uses */
@import url("@luz-ds/catalog/components/hero.css"); /* a pattern of a kind of site is a catalog component too */

Tu hoja de estilos importa un archivo después de la declaración, así que el orden queda fijado antes de que se cargue LUZ.