With a bundler or framework

The imports

Import the CSS of each package you use, tokens first, and the script if you want behaviour. A bundler resolves these names from node_modules; a <link> in HTML cannot.

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

• The tokens come first: every other package needs them.
• The navbar, the sidebar, the terminal and the timeline are catalog components: @luz-ds/core/css does not include them, so import @luz-ds/catalog/components/<name>.css for each one you use.
• import "@luz-ds/core" is the script. It is optional: every LUZ page works without it.
• To load less CSS, import @luz-ds/core/base.css and then one file per component, for example @luz-ds/core/components/button.css.
• To load one script module, import it by name and call its function: see JavaScript modules.

For the lines that match what you are building, with the CDN tags and their integrity hashes, choose your snippet.

Every name above is an entry of the exports map of its package. This table lists all of them.

The layer order survives bundling

Every CSS file LUZ publishes starts with the same @layer statement, which declares the order of all of LUZ's layers. So the order is the same however your tool splits, reorders or joins the files: the first one to load sets it.

In the Astro build below, the layers came out in the declared order, luz.tokens first and luz.print last, and an unlayered rule of the consumer came last.

CSS of your own that is outside any layer wins over every layer of LUZ, in any position, with no !important. Cascade layers has the full list and how to override one.

Astro, step by step

A new Astro project with LUZ's tokens and core, a layout that loads them, and CSS of your own that comes last.

Built with Astro 7.3 on 2026-10-15. LUZ is in beta and Astro changes between releases, so this page is dated: if a step fails on a newer Astro, check that release's notes first.

The build used packages packed from the LUZ repository at version 0.0.0, installed with npm install --legacy-peer-deps, because the peer ranges of ^0.1.0 do not resolve until 0.1.0 is published. After that, the command below needs no flag.

The project

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 stays as Astro creates it. LUZ needed no setting in it.

The commands

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

The layout

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

Your CSS and the page

/* 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>

The rule in site.css sets the type knob to 1.125rem and wins over LUZ's default without a layer and without !important. Make it yours has the other knobs.

What the build showed

• astro build and astro dev both worked with the two CSS imports in the frontmatter of a layout and no setting in astro.config.mjs.
• Astro bundled the <script> with import "@luz-ds/core" into one module file and split the lazy chunks off it.
• The fonts came out as hashed files, and the layers and your own rule came out in the order described above.

The build output was inspected, and the built page was not opened in a browser. Astro with a view transition router (<ClientRouter />) was not tried, and neither was Windows.

The import of a pattern of a kind of site has the same shape as the search one above, and was not built.

Vite, Next, Nuxt and SvelteKit

Only Astro was built for this page; Vite on its own, Next, Nuxt and SvelteKit were not built or tested. The imports are the same ones, in the root layout or the entry file of the app.

Each tool's own documentation says where CSS from a package goes:

• Vite documentation
• Next.js documentation
• Nuxt documentation
• SvelteKit documentation

One fact is the same for all of them. A LUZ module has no side effect when it is imported, until you call its init function, and luz.js and catalog.js check that document exists first.

So a framework that renders on the server can import them. In plain Node, with no document, ten modules of core and catalog were imported with no error.

Fonts and assets

@luz-ds/tokens/css is luz-tokens.css, and its @font-face rules point at the ET Book files with url(). Your bundler resolves those paths: Astro emitted the files as hashed woff2 assets.

To skip ET Book, import @luz-ds/tokens/tokens.css instead. It has the same tokens and no @font-face, so no font is downloaded.

Then set --luz-font-body to the font you use: Make it yours shows how.

A CDN in a framework

You can load LUZ from a CDN in a framework layout instead of importing it. In an Astro layout, a <link rel="stylesheet"> in the <head> and a <script type="module" src="https://…">, each with integrity and crossorigin, stay as written.

So does a script with is:inline. Astro only processes a <script> that has no attribute other than src.

Use the CDN or the imports, not both: LUZ would load twice. Choose your snippet gives the tags with their hashes.

If something does not work

• A warning about a peer dependency. @luz-ds/core asks for @luz-ds/tokens at ^0.1.0 || ^0.2.0 || ^0.3.0 || ^0.4.0. Install both, at the same version: npm install @luz-ds/tokens @luz-ds/core.
• The tool cannot resolve @luz-ds/core/css. The export is ./css, with no file extension. If your tool reports an unresolved import, add the package to vite.ssr.noExternal, as Astro's styling guide describes.
• The styles come out in the wrong order. Two copies of LUZ on the page, for example one from a CDN and one from your bundler, put their rules in the same layers: load it once. An @import with layer(luz) nests the names as luz.luz.components: drop the layer(). Cascade layers explains the order.

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

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