LeanCSS

Define sets. Lift them into components. Ship lean CSS.

LeanCSS is a CSS-first utility composition tool.

It lets you define reusable style bundles with @set (or @drop), then expand them inside selectors using @lift.

Unlike utility-class frameworks, LeanCSS keeps styling in CSS instead of HTML while still enabling composable, reusable patterns.

LeanCSS runs at build time and outputs plain CSS.

Why LeanCSS?

Modern CSS tooling tends to fall into two camps.

Utility frameworks

Example:

<button class="inline-flex items-center gap-2 px-4 py-2 rounded-md">

What is this?

Pros

• fast to prototype

• composable

Cons

• styles move into markup

• semantics become unclear

• component styles become fragmented

Sass mixins

Example:

.button {
@include flex-center;
}

Pros

• reusable abstractions

Cons

• hidden logic

• hard to inspect

• often grows into a mini programming language

LeanCSS approach

LeanCSS keeps composition inside CSS itself.

Example:

@set inline-flex {
display: inline-flex;
}
@set items-center {
align-items: center;
}
@set gap-2 {
gap: var(--space-2);
}
.button {
@lift inline-flex items-center gap-2;
}

Output:

.button {
display: inline-flex;
align-items: center;
gap: var(--space-2);
}

Features

LeanCSS is intentionally simple.

• CSS-first authoring
• reusable style bundles via @set and @drop
• composition via @lift
• alias sets
• cascade layer friendly
• works with .css and .scss
• outputs plain CSS
• zero runtime

Installation

npm install @bizrk/leancss

Add LeanCSS to your PostCSS configuration.

Example (postcss.config.mjs):

import leancss from "@bizrk/leancss"  

export default {  
  plugins: [  
    leancss()  
  ]  
}

Note: LeanCSS exports both CommonJS and ECMAScript modules out-of-the-box. If your modern framework (like Vite) enforces "type": "module", you can safely use postcss.config.js or postcss.config.mjs using import. If using CommonJS, use postcss.config.cjs and require("@bizrk/leancss").

LeanCSS runs during the CSS build process.

Editor Support (VS Code)

To prevent VS Code from reporting "Unknown at-rule" warnings for @set and @lift, you can configure custom CSS data.

Create .vscode/leancss.css-data.json:

{
  "version": 1.1,
  "atDirectives": [
    {
      "name": "@set",
      "description": "LeanCSS: Defines a reusable declaration bundle or alias bundle."
    },
    {
      "name": "@drop",
      "description": "LeanCSS: Like @set, but additionally generates a CSS class of the same name."
    },
    {
      "name": "@lift",
      "description": "LeanCSS: Expands one or more sets into the current selector rule."
    }
  ]
}

Then tell VS Code to use it in .vscode/settings.json:

{
  "css.customData": ["./.vscode/leancss.css-data.json"],
  "scss.customData": ["./.vscode/leancss.css-data.json"]
}

Basic Usage

Define reusable sets.

@set inline-flex {
display: inline-flex;
}
@set items-center {
align-items: center;
}
@set gap-2 {
gap: var(--space-2);
}

Use them in selectors.

.button {
@lift inline-flex items-center gap-2;
}

LeanCSS expands the sets during compilation.

Drop utility groups

Sometimes you want a defined set to also be available as a regular CSS class without having to manually map it. You can use @drop instead of @set.

@drop container { max-width: 1200px; }

This does two things:

1. It registers container so it can be used with @lift container.
2. It outputs a .container { max-width: 1200px; } class directly in your CSS.

CLI Tools

LeanCSS is reversible and comes with maintenance tools to keep your project clean.

You can run these commands via npx leancss <command>:

Trim

Keep the registry lean with trim, which removes unused patterns and optionally flattens weak ones.

# Preview what would be removed
npx leancss trim

# Actually remove unused patterns
npx leancss trim --write

# Automatically flatten patterns only used 1 time into their parent selector
npx leancss trim --write --single-use

Deload

If a project is finished, handed off, or simply no longer needs the abstraction layer, you can deload back to plain CSS at any time.

This flattens LeanCSS back into standard CSS.

# Preview what would be flattened
npx leancss deload

# Flatten every @lift into plain CSS
npx leancss deload --write

# Flatten every @lift AND remove the original @set declarations entirely
npx leancss deload --write --clean

Alias Sets

Sets can compose other sets.

Example:

@set flex-center {
@lift inline-flex items-center justify-center;
}

Usage:

.icon {
@lift flex-center;
}

Output:

.icon {
display: inline-flex;
align-items: center;
justify-content: center;
}

Cascade Layers

LeanCSS works well with CSS cascade layers.

Example:

@layer reset, tokens, base, utilities, components, overrides;

Define sets in a utilities layer:

@layer utilities {
@set inline-flex {
display: inline-flex;
}
@set items-center {
align-items: center;
}
}

Consume them in components:

@layer components {
.button {
@lift inline-flex items-center;
}
}

LeanCSS preserves layer ordering.

Example Project Structure

src/styles
├─ tokens.css
├─ utilities.css
├─ base.css
├─ components
│ ├─ button.css
│ ├─ card.css
│ └─ hero.css
└─ app.css

Example utilities file:

@layer utilities {  
  @set inline-flex {  
    display: inline-flex;  
  }  

  @set items-center {  
    align-items: center;  
  }  

  @set gap-2 {  
    gap: var(--space-2);  
  }  

  @set rounded-md {  
    border-radius: var(--radius-md);  
  }  
}

Example component:

.button {  
  @lift inline-flex items-center gap-2 rounded-md;  
}

Running PostCSS

You can use the postcss-cli package to compile your CSS. Add these scripts to your package.json:

{
  "scripts": {
    "build:css": "postcss src/styles/app.css -o dist/output.css",
    "watch:css": "postcss src/styles/app.css -o dist/output.css --watch"
  }
}

Run npm run build:css to build your styles once for production, or npm run watch:css while actively developing to automatically re-compile whenever you save your CSS files.

Philosophy

LeanCSS focuses on small, composable primitives.

It encourages:

• semantic selectors
• design token usage
• cascade layers
• small reusable patterns

It intentionally avoids:

• HTML class scanning
• runtime styling engines
• heavy configuration files

LeanCSS is designed to remain small, predictable, and easy to reason about.

Error Handling

LeanCSS validates styles during compilation.

Unknown set

.button {
@lift missing-set;
}

Error:

Unknown LeanCSS set: missing-set

Duplicate set

@set panel { ... }
@set panel

Error:

Duplicate LeanCSS set definition: panel

Circular reference

@set a { @lift b }
@set b

Error:

Circular set reference detected

Comparison

| Tool | Composition Location | | --- | --- | | Tailwind | HTML | | Sass mixins | Sass | | LeanCSS | CSS |

LeanCSS combines composability with semantic CSS architecture.

License

LeanCSS is released under the MIT License.

Contributing

Contributions are welcome.

Areas that benefit from community help:

• integrations
• preset libraries
• documentation
• testing

Future Ideas

LeanCSS v1 focuses on a minimal core.

Possible future additions include:

• preset utility libraries
• devtools for inspecting @lift expansion
• design system integrations

LeanCSS

Define sets. Lift them into components.