Lumo CSS Framework (Legacy)

4.0.10 · deprecated · verified Sun Apr 19

The `lumo-css-framework` package provides a set of utility-first CSS classes and foundational styles derived from Vaadin's Lumo design system. It was designed to help developers build web applications with a consistent Vaadin Lumo theme, offering customizable style properties like colors, fonts, sizing, spacing, and icons, along with dark and compact variants. While this specific npm package (version 4.0.10, last updated over five years ago) saw use in older Vaadin projects (pre-Vaadin 20), it is now considered deprecated. For current Vaadin applications (Vaadin 20+), the utility classes and Lumo theme are either built directly into the Vaadin framework or available through the actively maintained `@vaadin/vaadin-lumo-styles` package, which is part of the broader `web-components` monorepository and receives regular updates (current stable version 24.10.0). Users are strongly advised against using this standalone `lumo-css-framework` package for new projects or upgrading existing ones, and should instead rely on the integrated Vaadin theming or `@vaadin/vaadin-lumo-styles` for web component-based projects. Key differentiators of Lumo include its deep integration with Vaadin components, robust CSS custom property system for theming, and comprehensive set of utility classes for flexible layouting, which conform to some Tailwind CSS patterns.

Common errors

```
Error: Can't resolve 'lumo-css-framework/all-classes.css'
```
cause The `lumo-css-framework` package is not installed or the import path is incorrect/outdated for your Vaadin version.

fix Ensure `lumo-css-framework` is listed in your `package.json` and installed via `npm install`. For Vaadin Flow projects, check that the `@NpmDependency` annotation (if used) is correct, or if you're on Vaadin 20+, remove this dependency and rely on built-in Lumo support or `@vaadin/vaadin-lumo-styles`.
```
CSS custom property '--lumo-primary-color' not found / '--lumo-font-size-m' is undefined
```
cause Lumo's base styles (defining these CSS variables) are not correctly imported or are being overridden/missing in your project's theme configuration.

fix Verify that `all-classes.css` or the appropriate Lumo base styles are correctly imported at the beginning of your main stylesheet. If using a custom Vaadin theme, ensure the theme setup is correct and not inadvertently blocking Lumo's variable definitions. Check Vaadin documentation for how to properly extend or override Lumo variables.

Warnings

breaking The `lumo-css-framework` npm package (version 4.0.10 and earlier) is officially deprecated. Its functionality, particularly utility classes, has been integrated directly into Vaadin versions 20 and newer. For web components, use `@vaadin/vaadin-lumo-styles` instead. Continuing to use this package in newer Vaadin setups may lead to conflicts, outdated styles, or redundant imports.
Fix: For new Vaadin projects (Vaadin 20+), avoid `lumo-css-framework`. Rely on Vaadin's built-in theming system. For web component projects, use `npm install @vaadin/vaadin-lumo-styles`. Refer to Vaadin's official documentation for migration guidance and modern usage patterns.
breaking Vaadin 25+ introduces a new default theme called 'Aura'. Migrating from Lumo to Aura involves significant changes to CSS custom properties (e.g., `--lumo-*` to `--vaadin-*` or `--aura-*`) and a re-evaluation of how utility classes are used. Direct Lumo styling will be incompatible with Aura.
Fix: If migrating to Vaadin 25+ (or using Aura theme), carefully review the Vaadin migration guides for Lumo to Aura. Be prepared to update CSS variable names and potentially switch to other utility class systems like Tailwind CSS if not using Vaadin's built-in options.
gotcha This package is purely a CSS framework; it does not export any JavaScript symbols. Attempting to `import` named or default exports from `lumo-css-framework` in JavaScript or TypeScript files will result in build errors.
Fix: Always import CSS files using side-effect imports (e.g., `import 'lumo-css-framework/all-classes.css';`) in JavaScript/TypeScript bundler setups, or use `<link>` tags in HTML or `@import` rules in CSS files.

Install

npm install lumo-css-framework npm
yarn add lumo-css-framework yarn
pnpm add lumo-css-framework pnpm

Imports

Lumo global styles and utility classes
wrong:
```
import { Lumo } from 'lumo-css-framework'; // No JS exports
```
correct:
```
import 'lumo-css-framework/all-classes.css';
```
This package is CSS-only. For Vaadin Flow projects, `all-classes.css` or `classes.css` would typically be imported via a `@CssImport` annotation in Java or referenced in `styles.css` within your Vaadin theme folder for older versions.
Lumo utility classes (subset)
wrong:
```
import 'lumo-css-framework/all.css'; // Common typo, should be all-classes.css or just classes.css
```
correct:
```
import 'lumo-css-framework/classes.css';
```
For specific utility classes without all base Lumo styles. The recommended approach for Vaadin 20+ is often to leverage built-in theming or the `@vaadin/vaadin-lumo-styles` package.
Including via HTML link tag (for basic usage)
wrong:
```
<style>@import 'lumo-css-framework';</style> // Requires a specific file path
```
correct:
```
<link rel="stylesheet" href="node_modules/lumo-css-framework/all-classes.css">
```
This direct link method is common in simpler setups or for direct browser consumption. In Vaadin projects, a build process usually handles these imports.

Quickstart

Demonstrates how to import the Lumo CSS framework's styles in a Vaadin project's main stylesheet and provides context on its deprecation.

/* src/main/frontend/themes/my-app/styles.css */
/* This example assumes a Vaadin Flow project structure */
/* For Vaadin 19 and earlier, using the lumo-css-framework npm package */

@import url('lumo-css-framework/all-classes.css');

/* You can also import specific parts, e.g., only utility classes */
/* @import url('lumo-css-framework/classes.css'); */

/* Add your custom styles here, overriding Lumo variables if needed */
:host([theme~="my-app"]) {
  --lumo-primary-color: #694CFA;
  --lumo-primary-color-50pct: rgba(105, 76, 250, 0.5);
  --lumo-font-family: 'Inter', sans-serif;
}

/* Example of using Lumo utility classes in HTML/JSX/TSX */
// <div class="flex flex-col items-center justify-center p-l"></div>

/* For Vaadin 20+ applications, the lumo-css-framework package is deprecated. */
/* Lumo utility classes are often directly available or via @vaadin/vaadin-lumo-styles. */
/* Example for Vaadin 20+ with built-in utility classes (no direct lumo-css-framework import needed) */
// @CssImport(value = "./themes/my-app/styles.css", themeFor = "vaadin-app-layout")
// @Theme("my-app")

view raw JSON →