How LUZ is organised

Package boundaries

Each package depends on the ones above it in this list, never on the ones below.

The name stands for Light, Usable & Zero-dependency: light in weight (plain CSS and ES modules, nothing to build for the people who use it), usable by everyone (native HTML, three color modes, tested for accessibility), and with zero runtime dependencies.

@luz-ds/tokens   -> primitive and semantic tokens (standalone)
      ↓ required by
@luz-ds/core     -> components, objects, bare-element styles, optional JS
      ↓ required by
@luz-ds/catalog     -> search, cookie-consent, theme-time, lang-switch, submenu, announcement, and the patterns of a landing page, a blog or newspaper, a web application and a documentation site

• The catalog needs core and tokens; core needs tokens; tokens needs nothing.
• Tokens, core and catalog share one version. There are no packages for one kind of site: the patterns of a landing page, a blog, an application or a documentation site are components of the catalog, one file each.
• The packages say so as peer dependencies. The core and catalog scripts warn in the console when a level is missing.

The documentation follows the packages, with one area more: Kinds of site puts together, for each kind, the prompt for an LLM and the recipes of its parts, made of the packages above and of the patterns of that kind in the catalog.

What each package needs

Find the part you want, and install the package of its row and the ones below it.

• Two ways to lay out a page, both core's. .o-shell with .o-main: a sidebar column beside the main area. .o-page: a header, the content and a footer in one column. Pick one for the grid of the page: the first when it has a sidebar, the second when it has none. A landing or CMS header and footer work with both; these docs use .o-shell.
• The catalog needs core, and core needs tokens, so a row at a level also needs every package under it. The patterns of a landing page, a blog, an app and a documentation site are catalog components, so they need core and tokens too.

CSS layers

Core's CSS comes in native cascade layers (@layer), in ITCSS order, inside one container layer called luz. The six below are the ones that hold its rules; the layers page lists them all, with tokens, catalog and print.

A later layer wins over an earlier one, and any CSS of yours that is not in a layer wins over all of LUZ, with no !important. How to order and override them.

packages/core/src/
  settings/_settings.css      luz.settings    z-index, layout widths, field text
  generic/_reset.css          luz.generic     the reset
  elements/*.css              luz.elements    bare HTML elements, zero specificity
  objects/_objects.css        luz.objects     layout: .o-*
  components/*.css            luz.components  the components: .luz-*
  utilities/_utilities.css    luz.utilities   single-purpose helpers: .u-*

• The components layer holds 29 components.
• dist/luz.css holds these six layers and luz.print. Tokens are in luz.tokens, catalog, with the navbar, the sidebar, the terminal, the timeline and the patterns of a kind of site, in luz.catalog; luz.themes is empty, kept for a look of your own. For a page that needs a few components only, load dist/base.css (settings, reset and elements), then dist/components/<name>.css for each one.
• Rules for bare elements are wrapped in :where(), so any class wins over them.

The script

One optional entry point, luz.js, starts every behaviour on the page: color mode, copy buttons, dialogs, highlighting, players and tabs.

<script type="module" src="https://cdn.jsdelivr.net/npm/@luz-ds/core@0.3.0/dist/luz.min.js"></script>

To load less, import one module and call its init function. See JavaScript modules.

Minimal page

<!doctype html>
<html lang="en" data-theme="light">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Sign up – Acme</title>
  <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">
</head>
<body>
  <main class="o-container">
    <h1>Sign up</h1>
    <form action="/signup/" method="post">
      <div class="luz-field">
        <label class="luz-field__label" for="email">Email</label>
        <input class="luz-input" id="email" name="email" type="email" autocomplete="email" required>
      </div>
      <button class="luz-btn luz-btn--primary" type="submit">Create account</button>
    </form>
  </main>
</body>
</html>