Theming

#Cascade layers

The components' stylesheets hold only what a component needs to work (display, positioning and anchoring, the top layer, the CSS variables a component sets), in the lu.core cascade layer. The default theme sits in lu.theme, above it:

import "@lumiose/ui/styles.css"; // what every component needs (or "@lumiose/ui/dialog.css", …)
import "@lumiose/ui/themes/default.css"; // optional: the default theme

Both stylesheets declare the layers lu.core, lu.theme, in that order. CSS outside layers always wins over layered CSS, so your own stylesheets override the package's without specificity games. If your app orders its own layers, put lu first: @layer lu, reset, components;.

#The default theme

@lumiose/ui/themes/default.css is a ready look for demos, prototypes and getting started: neutral surfaces, a blue primary, light and dark. It styles a few classes, which you put on the parts through their class prop:

Its colours and radius are custom properties with shadcn/ui's names and a --lu- prefix, so a shadcn palette carries over:

The theme sets color-scheme: light dark on :root and every colour with light-dark(), so it follows the system. Set color-scheme: light (or dark) on :root or on any element, in CSS, inline or from a script, to force one, in development and in production builds alike (Lumiose's CSS target keeps light-dark() as written; an older build.cssTarget would lower it to colours that follow the system only). Redefine a property outside layers to change it:

:root {
  --lu-primary: #7c3aed;
  --lu-radius: 0.375rem;
}

The theme meets WCAG 2.2 AA in light and dark: each -foreground colour reaches 4.5:1 on its surface, and --lu-input (the borders of fields and controls) and --lu-ring (the focus ring) reach 3:1 on the surfaces they sit on. --lu-border is for decoration, such as a dialog's edge: it is too light to outline a control. Keep those ratios when you change the colours.

In forced colours (Windows' contrast themes), the browser drops shadows and gradients and paints backgrounds in its own palette, which would erase the state a colour shows. The theme draws those states again in system colours (Highlight, HighlightText, ButtonText, Canvas): a switch's thumb and its on state, a pressed toggle, the selected tab's bar, progress and meter values, a slider's range, the scroll thumb and the highlighted menu item. A pressed toggle's focus ring, outside its Highlight fill, is CanvasText, the colour every contrast theme pairs with the page (Firefox would draw it in the toggle's HighlightText). Do the same for the states your own CSS draws with a colour, in a @media (forced-colors: active) block.

#Your own CSS

Style the parts through:

• Class props. Every part takes class (and style), like the element it renders.
• State. Components expose state the way the platform does, so selectors read it directly: dialog[open], :modal, ::backdrop, :popover-open, [aria-expanded], [aria-checked], [aria-selected]. Where the platform has no such state, they set Base UI's state attributes: data-highlighted on the active option of a list, data-side and data-align on a placed popup, data-orientation, data-starting-style and data-ending-style while a popup animates, data-swiping, data-indeterminate and others. Each component's page lists its own.
• Custom properties. The values components measure or place, such as a panel's height, a toast's index in its stack or a popup's offset, are custom properties with the --lu- prefix. Base UI names them without a prefix, so its --collapsible-panel-height is --lu-collapsible-panel-height here and its --scroll-area-thumb-height is --lu-scroll-area-thumb-height.

Other data-* attributes on the rendered HTML, such as the markers scripts use to find a part or the settings the server HTML passes to a script, are internal and may change between versions. Style those parts through their class props.

Each component's page has an example stylesheet to start from.

#Related

• UI components: the approach and the components.
• Installation: adding the package and importing its stylesheets.
• Styles: scoped CSS and global stylesheets in Lumiose.