KOSS

KOSS (KOmmand CSS) is a high-performance, flexible Atomic CSS-in-JS library designed for modern web applications. It combines the power of JavaScript-driven styling with the performance of atomic CSS and the latest browser features.

🚀 Key Features

• ⚡ Atomic Engine: Automatically generates minimal, reusable atomic CSS classes using MurmurHash, keeping your production CSS footprint ultra-small.
• 🎭 Functional Themes: Deeply integrated theme system supporting (theme) => style functions for dynamic design tokens.
• 🧪 Modern CSS Support: First-class support for @container queries, @layer cascade layers, and @starting-style.
• ✨ CSS Houdini: Built-in @property registration via addProperty for buttery-smooth CSS variable transitions.
• 🛡️ Type-Safe: Fully powered by TypeScript with template literal types for nested selectors (& > div, @media, etc.).
• 🏎️ Performance Optimized: Implements a Reference Counting GC for styles and $O(1)$ rule removal logic to prevent memory leaks and UI jank.

📦 Installation

npm i -S koss

🛠️ Quick Start

Basic Usage

import { CSSManager } from "koss";

// 1. Define your design tokens or theme
const theme = {
    primary: "hsla(210, 100%, 50%, 1)",
    radius: "12px",
};

// 2. Initialize the manager
const cssManager = new CSSManager(theme);

// 3. Generate atomic styles
const styles = cssManager.addStyles({
    button: {
        backgroundColor: (theme) => theme.primary,
        borderRadius: (theme) => theme.radius,
        padding: "10px 20px",
        transition: "transform 0.2s",
        "&:hover": {
            transform: "scale(1.05)",
        },
        "@media (max-width: 600px)": {
             padding: "8px 16px",
        }
    }
});

function App() {
    return <button className={styles.button}>Click Me</button>;
}

🌟 Advanced Features

CSS Houdini & Smooth Transitions

Use @property to enable smooth transitions for CSS variables that browsers normally can't animate.

cssManager.addProperty("--accent-color", {
    syntax: '"<color>"',
    inherits: true,
    initialValue: "#ff0000",
});

const className = cssManager.addStyle({
    color: "var(--accent-color)",
    transition: "color 0.4s ease",
});

Modern Rules: Container Queries & Layers

KOSS stays ahead of the curve with native support for the latest CSS specifications.

// Cascade Layers for priority management
cssManager.addLayer("framework", {
    ".reset": { margin: 0 }
});

// Container Queries for component-level responsiveness
cssManager.addContainer("(min-width: 500px)", {
    sidebar: { display: "block" }
});

Keyframes & Animations

cssManager.addKeyframes("fade-in", {
    from: { opacity: 0 },
    to: { opacity: 1 }
});

const fadeCls = cssManager.addStyle({
    animation: "fade-in 1s ease-out"
});

⚙️ Performance & Architecture

Unlike many CSS-in-JS libraries that cause style bloat or slow unmounting, KOSS uses an advanced Reference Counting mechanism.

• Styles are only removed from the DOM when no remaining components are using that specific atomic rule.
• Removal logic uses a prioritized index cache, ensuring $O(1)$ lookup time regardless of total rules.

📜 License

MIT © 2026 KOSS Team