@bizrk/leancss 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Birkner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { PluginCreator } from 'postcss';
+interface LeanCssOptions {
+}
+declare const leancss: PluginCreator<LeanCssOptions>;
+export default leancss;

package/dist/index.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const leancss = (opts = {}) => {
+    return {
+        postcssPlugin: 'leancss',
+        Once(root, { result }) {
+            const sets = new Map();
+            // 1. Collect and Validate sets
+            root.walkAtRules('set', (atRule) => {
+                const name = atRule.params.trim();
+                if (!name) {
+                    atRule.warn(result, 'Missing name for @set');
+                    return;
+                }
+                if (sets.has(name)) {
+                    throw atRule.error(`Duplicate @set definition for "${name}"`);
+                }
+                let isAlias = false;
+                // Validate contents
+                atRule.walk((node) => {
+                    if (node.type === 'atrule') {
+                        const atNode = node;
+                        if (atNode.name !== 'lift') {
+                            throw node.error(`Unsupported at-rule @${atNode.name} inside @set. Only @lift is allowed.`);
+                        }
+                        isAlias = true;
+                    }
+                    else if (node.type === 'rule') {
+                        throw node.error(`Nested selectors are not supported inside @set in v1.`);
+                    }
+                    else if (node.type !== 'decl' && node.type !== 'comment') {
+                        throw node.error(`Unsupported node type "${node.type}" inside @set.`);
+                    }
+                });
+                sets.set(name, {
+                    name,
+                    sourceFile: atRule.source?.input.file,
+                    node: atRule,
+                    isAlias,
+                    resolvedDeclarations: [] // Will be populated in resolution phase
+                });
+            });
+            // 3. Resolve aliases
+            function resolveSet(name, resolutionChain, originNode) {
+                const setDef = sets.get(name);
+                if (!setDef) {
+                    throw originNode.error(`Unknown set "${name}" referenced in @lift`);
+                }
+                // Cache hit
+                if (setDef.resolvedDeclarations.length > 0) {
+                    return setDef.resolvedDeclarations;
+                }
+                // It might be empty, let's distinguish between empty resolution and unresolved by adding a flag or just always resolving. 
+                // Circular detection
+                if (resolutionChain.includes(name)) {
+                    const chain = [...resolutionChain, name].join(' -> ');
+                    throw originNode.error(`Circular alias reference detected: ${chain}`);
+                }
+                const currentChain = [...resolutionChain, name];
+                const resolved = [];
+                setDef.node.walk((node) => {
+                    if (node.type === 'decl') {
+                        resolved.push(node.clone());
+                    }
+                    else if (node.type === 'atrule') {
+                        const atNode = node;
+                        if (atNode.name === 'lift') {
+                            const refs = atNode.params.split(/\s+/).filter(Boolean);
+                            for (const ref of refs) {
+                                const expanded = resolveSet(ref, currentChain, atNode);
+                                for (const decl of expanded) {
+                                    resolved.push(decl.clone());
+                                }
+                            }
+                        }
+                    }
+                });
+                setDef.resolvedDeclarations = resolved;
+                return resolved;
+            }
+            // Resolve all sets eagerly (or could be done lazily when expanding selector-level @lift)
+            for (const [name, setDef] of sets.entries()) {
+                if (setDef.resolvedDeclarations.length === 0) {
+                    resolveSet(name, [], setDef.node);
+                }
+            }
+            // 4. Expand selector-level @lift
+            root.walkAtRules('lift', (atRule) => {
+                // Ignore @lift inside @set
+                let parent = atRule.parent;
+                let inSet = false;
+                while (parent) {
+                    if (parent.type === 'atrule' && parent.name === 'set') {
+                        inSet = true;
+                        break;
+                    }
+                    parent = parent.parent;
+                }
+                if (inSet)
+                    return;
+                if (atRule.parent?.type !== 'rule') {
+                    throw atRule.error(`@lift is only allowed inside standard rules or @set blocks in v1.`);
+                }
+                const refs = atRule.params.split(/\s+/).filter(Boolean);
+                const declsToInsert = [];
+                for (const ref of refs) {
+                    const setDef = sets.get(ref);
+                    if (!setDef) {
+                        throw atRule.error(`Unknown set "${ref}" referenced in @lift`);
+                    }
+                    for (const decl of setDef.resolvedDeclarations) {
+                        declsToInsert.push(decl.clone());
+                    }
+                }
+                atRule.replaceWith(...declsToInsert);
+            });
+            // 5. Remove @set definitions
+            root.walkAtRules('set', (atRule) => {
+                atRule.remove();
+            });
+        }
+    };
+};
+leancss.postcss = true;
+exports.default = leancss;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bizrk/leancss",
+  "version": "0.1.0",
+  "description": "CSS-first utility composition with @set and @lift that provides a clean, layer-aware alternative to Sass mixins and Tailwind @apply for atomic compositions.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "directories": {
+    "test": "tests"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "css",
+    "postcss",
+    "postcss-plugin",
+    "utility",
+    "atomic",
+    "composition",
+    "design-system",
+    "leancss",
+    "set",
+    "lift"
+  ],
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "author": "Adam Birkner",
+  "license": "MIT",
+  "peerDependencies": {
+    "postcss": "^8.0.0"
+  },
+  "devDependencies": {
+    "postcss": "^8.4.38",
+    "@types/node": "^20.12.7",
+    "typescript": "^5.4.5",
+    "vitest": "^1.5.0"
+  }
+}

package/readme.md

@@ -0,0 +1,410 @@
+# 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`, 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;  
+}  
+<br/>@set items-center {  
+align-items: center;  
+}  
+<br/>@set gap-2 {  
+gap: var(--space-2);  
+}  
+<br/>.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`  
+• 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:
+
+```javascript
+import leancss from "@bizrk/leancss"  
+```
+export default {  
+plugins: \[  
+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`:
+
+```json
+{
+  "version": 1.1,
+  "atDirectives": [
+    {
+      "name": "@set",
+      "description": "LeanCSS: Defines a reusable declaration bundle or alias bundle."
+    },
+    {
+      "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`:
+
+```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;  
+}  
+<br/>@set items-center {  
+align-items: center;  
+}  
+<br/>@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.
+
+* * *
+
+# 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;  
+}  
+<br/>@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:
+
+```css
+@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:
+
+```css
+.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`:
+
+```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.**