How to read LUZ

Class names

The start of a class name tells you what it is and which package it comes from.

Inside a component, two separators say how the pieces fit. A double underscore names a part of the component: .luz-card__title is the title of a card.

A double hyphen names a variant of it: .luz-btn--primary is the primary button.

Read this markup from left to right, one class at a time.

<div class="o-stack">
  <article class="luz-card">
    <h3 class="luz-card__title">Team plan</h3>
    <button class="luz-btn luz-btn--primary" type="button">Choose plan</button>
  </article>
</div>

• o-stack is a layout object: it spaces its children in a column.
• luz-card is a component, a card.
• luz-card__title is a part of the card: its title.
• luz-btn is another component, a button, and luz-btn--primary is its primary variant.

Token names

A token is a CSS custom property that starts with --luz-. The next word says what kind of value it holds.

• LUZ's own components read semantic tokens and scale steps. They never read a primitive or a knob.
• You can set any token in your own CSS. Make it yours shows how.

Each family has a page: color, typography, spacing and sizing, radius, shadows, motion and layout and breakpoints.

Attributes

Classes are for style. Attributes that start with data- are how a script and your markup talk to each other.

• data-theme on <html> picks the color mode (light, dark or high-contrast) or the name of a look of your own.
• data-mode on <html> picks the color mode inside a look of your own: data-theme="my-brand" with data-mode="dark".
• data-luz-* are the hooks of LUZ's scripts, such as data-luz-js, which the script sets on <html> once it runs. A script binds to these, never to a class.
• data-luz marks a zone for luz.conditional.css: the reset and the bare elements apply only inside it.
• data-luz-label-* overrides one string a script writes.

These are examples, not the full list: each component's page names the attributes it uses.

Elements that start with luz

A tag that starts with luz- is a custom element. LUZ's are in the light DOM, so your CSS reaches inside them, and their parts are classes: .luz-<tag>__<part>.

• With a script: <luz-search>, <luz-cookie-consent>, <luz-theme-mode>, <luz-theme-time> and <luz-timeline> need their script to do their job.
• CSS only: <luz-lang-switch>, <luz-submenu> and <luz-announcement> have no script at all. They are a tag you can style before and without its script.

Which package holds each one is in How LUZ is organised.

Layers, in one paragraph

All of LUZ's CSS is in one cascade layer called luz, with named layers inside it, and any CSS of yours that is not in a layer wins over all of it, with no !important. Cascade layers lists them in order and shows how to override one.

What you can rely on

Not every name is a promise. These four parts of LUZ are public API: a change to them is announced.

• Tokens: every --luz- custom property in tokens.css, not the ones a component declares for itself.
• Classes: .luz-, .o- and .u- classes in the markup the docs show, with their parts and variants. Not .is- classes.
• Attributes: data-theme, data-mode, data-luz-* and data-luz-label-*. Not the attributes the docs site's own scripts use.
• Packages: the exports map of each package and the paths of the files it publishes.

In beta, anything may break, and the changeset of the release says how to migrate. Read What is public API, in VERSIONING.md on GitHub for the whole table.

Reading a file name

A file name says what is in it. Every CSS file also has a .min twin that holds the same rules, minified: luz.css and luz.min.css.

To pick the lines for your build, choose your snippet.