# PACKAGE: @nofinite/nuicss

Semantic CSS utility framework and runtime-less design token engine.

You are an expert CSS developer using @nofinite/nuicss.
Rules:
1. Always prefer NUICSS superclasses (btn, card, badge, input, textarea, switch, tabs, accordion, metric-card, chart-bar-horizontal) over raw atomic utility combinations.
2. Use semantic OKLCH design tokens: bg-surface, text-default, border-default, color-primary, etc. Never hardcode hex values.
3. Use native ARIA states (aria-selected="true", aria-expanded="true", aria-invalid="true", aria-checked="true") which NUICSS styles automatically without extra classes.
4. Supports responsive container queries (cq, card-responsive), fluid typography (text-fluid-*), and physics easings (ease-spring, press-scale, hover-lift).

---



### Document: nuicss/architecture/page.mdx

# Architecture & UnoCSS Engine

Understand the inner workings of NUICSS and how its on-demand compilation engine delivers instant styling.

---

## Evolution to the UnoCSS Engine

In previous iterations:
- **v1** relied on static, monolithic utility stylesheets that bloated production bundles.
- **v2** introduced a custom JIT engine, but had limited variant support, lacked modern CSS feature coverage, and suffered from edge cases.

**NUICSS** is architected directly on top of **UnoCSS**, the industry standard instant atomic CSS engine:
- **Instant Compilation**: Up to 5x faster than traditional CSS compilers.
- **Full Modern Syntax**: Supports arbitrary values (`w-[340px]`), variant groups (`hover:(text-primary font-bold)`), and media queries (`@screen md`).
- **Clean CSS Output**: Only emits classes that are actually used in your source code.

---

## The `@nuicss` Directive

When `@nuicss;` is placed in your stylesheet, the PostCSS/Vite plugin processes it into structured layers:

```css
/* Input: */
@nuicss;

/* Emitted Output: */
/* Layer: preflights (resets & normalize) */
/* Layer: default (design tokens & variables) */
/* Layer: shortcuts (reusable component aliases) */
/* Layer: utilities (atomic class rules) */
```

### Specific Layer Injection
You can also inject specific layers if you need custom ordering:

```css
@nuicss preflights;
@nuicss default;

/* Custom CSS between resets and utilities */
.my-custom-class {
  margin: 0 auto;
}

@nuicss utilities;
```

---

## Directives Support

### 1. `@apply`
Inline atomic utility classes into custom CSS declarations:

```css
.hero-card {
  @apply p-8 bg-surface border border-default rounded-xl shadow-md;
}
```

### 2. `@screen`
Write clean media queries matching your configured breakpoints:

```css
.sidebar {
  display: none;

  @screen md {
    display: flex;
    width: 280px;
  }
}
```

### 3. `theme()` Function
Extract values from your NUICSS theme directly in CSS:

```css
.custom-border {
  border-color: theme('colors.primary');
}
```

---


### Document: nuicss/cli/page.mdx

# NUICSS CLI & Standalone Compiler

The official standalone command-line compiler, linter, codemod, and component toolkit for the **NUICSS** design system.

---

## Overview

`nuicss` is the high-performance CLI compiler and developer toolkit for the NUICSS ecosystem. Engineered for **instant native execution (under 3ms startup)** and **zero runtime dependencies**, it compiles production stylesheets, migrates legacy utility soup into semantic superclasses, lints codebase styling compliance, and scaffolds components across any web stack.

- ⚡ **Instant Native Execution:** Available as single native standalone binaries for Windows, Linux, and macOS (compiled via Bun with zero Node.js required), or as a lightweight npm package.
- 🎯 **Universal File Watcher:** Natively watches and scans `.html`, `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, `.php`, `.templ`, `.blade.php`, `.jinja`, `.liquid`, `.twig`, `.ejs`, `.erb`, `.hbs`, `.mdx`, and arbitrary user globs.
- 🧠 **High-Throughput In-Memory Caching:** 50ms debounced build pipeline with single-file incremental re-reads and zero dropped file save events.
- 🎨 **Modular Layer Directives:** Granular stylesheet assembly via `@nuicss tokens;`, `@nuicss components;`, `@nuicss utilities;`, or unified `@nuicss;`.
- 🔄 **Local-First Resolution:** Automatically discovers and prioritizes local `node_modules/@nofinite/nuicss` in Node projects, with built-in embedded fallbacks for non-Node environments.
- 🗜️ **Production Minification:** Full-stylesheet compression powered by LightningCSS.
- 🚀 **In-CLI Self-Updater:** Seamless in-terminal binary upgrades via `nuicss upgrade`.

---

## Installation

### 1. Standalone Binary (Zero Node.js Required)

Install directly with a single terminal command:

#### Windows (PowerShell):

```powershell
irm https://opensource.nofinite.com/nuicss/install.ps1 | iex
```

#### macOS & Linux (Bash/Zsh):

```bash
curl -fsSL https://opensource.nofinite.com/nuicss/install.sh | bash
```

The installer automatically downloads the native binary for your architecture, sets permissions, and registers `nuicss` in your system `PATH`.

---

### 2. Via Package Managers

Run on-demand using your preferred package runner:

```bash
# npx
npx nuicss -i input.css -o dist/output.css --watch

# bunx
bunx nuicss -i input.css -o dist/output.css --watch
```

Or install globally:

```bash
# npm
npm install -g nuicss

# pnpm
pnpm add -g nuicss

# bun
bun add -g nuicss
```

---

## Quickstart Workflow

### 1. Initialize Configuration & IDE Autocomplete

Generate a type-safe `nuicss.config.ts` and configure native VS Code / Cursor autocomplete in `.vscode/settings.json`:

```bash
nuicss init
```

### 2. Create Your Input Stylesheet

Create your entry CSS file with the `@nuicss` directive:

```css
/* input.css */
@nuicss;

/* Or assemble modular layers independently: */
/* @nuicss tokens; */
/* @nuicss components; */
/* @nuicss utilities; */
```

### 3. Compile Stylesheets

Run one-time compilation or live watch mode:

```bash
# One-time production build with minification
nuicss -i input.css -o dist/output.css --minify

# Live watch mode
nuicss -i input.css -o dist/output.css --watch

# Live watch mode with custom template patterns
nuicss -i input.css -o dist/output.css --watch --watch-files "templates/**/*.jinja,views/**/*.liquid"
```

---

## Command Reference

| Command | Description | Example |
| :--- | :--- | :--- |
| `compile [patterns]` | Compile stylesheets into production CSS | `nuicss compile -i input.css -o dist/output.css -m` |
| `init` | Initialize configuration and IDE schemas | `nuicss init` |
| `add [component]` | Scaffold UI component and view starter markup | `nuicss add button`, `nuicss add dialog` |
| `check [path]` | Lint codebase for hardcoded hex and legacy soup | `nuicss check src/` |
| `migrate [path]` | Codemod migrating legacy utility soup to superclasses | `nuicss migrate templates/ --dry-run` |
| `tokens` | Inspect OKLCH color palettes and semantic tokens | `nuicss tokens` |
| `list` | List available components across Nofinite ecosystem | `nuicss list` |
| `upgrade` | Check and self-update nuicss to latest release | `nuicss upgrade`, `nuicss upgrade --check` |
| `version` | Print installed CLI version | `nuicss version` |

---

### Stylesheet Compilation (`nuicss compile`)

```bash
nuicss compile [patterns] [options]
```

#### Options:

- `-i, --input <file>`: Input CSS file path containing `@nuicss` directives (use `-` for stdin).
- `-o, --output <file>`: Output CSS file path (default: `dist/output.css`, use `-` for stdout).
- `-w, --watch`: Watch scanned files for changes and recompile incrementally.
- `--watch-files <patterns>`: Additional glob patterns to watch (comma-separated).
- `-m, --minify`: Compress output CSS using LightningCSS.
- `-c, --config <file>`: Path to custom configuration file (default: `nuicss.config.ts`).

#### Modular Layer Directives

NUICSS supports granular stylesheet assembly directly in your input CSS:

```css
/* 1. Only OKLCH color tokens, semantic variables, and modern reset */
@nuicss tokens;

/* 2. Only component superclasses (btn, card, input, badge, table, etc.) */
@nuicss components;

/* 3. Only scanned JIT utility classes extracted from your markup */
@nuicss utilities;

/* 4. Complete unified bundle (tokens + components + utilities) */
@nuicss;
```

---

### Component Scaffolding (`nuicss add`)

Scaffold components across the Nofinite ecosystem with clean starter markup:

```bash
nuicss add button
nuicss add dialog
nuicss add card
nuicss add badge
nuicss add table
nuicss add tabs
nuicss add dropdown
nuicss add chart
nuicss add sparkline
nuicss add kanban
nuicss add editor
nuicss add media
```

---

### Codebase Linting (`nuicss check`)

Audit your project to ensure strict adherence to the NUICSS design system:

```bash
nuicss check src/
```

- **Hex Literal Detection:** Flags un-tokenized `#hex` literals inside styling attributes (`style="..."`, `class="bg-[#...]"`), while ignoring regular anchor links (`<a href="#section">`).
- **Superclass Optimization:** Detects 15 legacy utility clusters from Tailwind/Bootstrap and recommends their semantic NUICSS replacements.

---

### Automated Codemod Migration (`nuicss migrate`)

Transform verbose utility soup into clean superclasses automatically:

```bash
# Preview changes safely without modifying files
nuicss migrate src/ --dry-run

# Apply transformations in-place
nuicss migrate src/
```

---

## Configuration (`nuicss.config.ts`)

NUICSS CLI natively evaluates `.ts`, `.mts`, and `.js` configuration files via `jiti`:

```ts
// nuicss.config.ts
import { defineConfig } from '@nofinite/nuicss';

export default defineConfig({
  // Custom scan targets
  content: [
    './templates/**/*.jinja',
    './views/**/*.html',
    './src/**/*.{tsx,jsx,vue}',
  ],
  // Additional watch directories
  watchFiles: ['./content/**/*.md'],
  theme: {
    // Custom design token overrides
    colors: {
      primary: '#09090b',
    },
  },
});
```

---

## Non-Node Framework Integration

Because `nuicss` is available as a standalone executable, it integrates seamlessly into backend stacks without requiring `npm` or `node_modules`:

### Go (Templ / HTML Templates)

```bash
# In Makefile or dev script:
nuicss -i static/input.css -o static/styles.css --watch --watch-files "views/**/*.templ"
```

### Python (Django / Flask / Jinja)

```bash
# Watch Jinja templates and write to static assets
nuicss -i static/css/input.css -o static/css/bundle.css --watch --watch-files "templates/**/*.html"
```

### PHP (Laravel Blade / Symfony Twig)

```bash
nuicss -i resources/css/input.css -o public/css/app.css --watch --watch-files "resources/views/**/*.blade.php"
```

---

## Self-Updating (`nuicss upgrade`)

Keep your standalone compiler up to date with zero friction:

```bash
# Check if an update is available
nuicss upgrade --check

# Self-update binary to the latest GitHub Release
nuicss upgrade
```

---

## Next Steps

- Explore [**Component Superclasses**](/nuicss/superclasses) for ready-to-use semantic classes (`btn`, `card`, `input`, `badge`).
- Learn how [**Theming & Design Tokens**](/nuicss/theming) leverage OKLCH and CSS variables for instant dark mode.
- Set up [**VS Code & Cursor IDE Autocomplete**](/nuicss/ide-setup) for instant class suggestions and hover previews.
- Read the [**Tailwind & Legacy CSS Migration Guide**](/nuicss/migration) for automated codebases upgrades.

---


### Document: nuicss/configuration/page.mdx

# Configuration

Configure NUICSS to fit your application structure, custom themes, and design tokens.

---

## Configuration File

NUICSS loads configuration from `nuicss.config.ts` (or `.js`, `.mjs`, `.cjs`) in your project root using the `defineConfig` helper:

```ts
import { defineConfig, nuicssPreset } from '@nofinite/nuicss';

export default defineConfig({
  presets: [
    nuicssPreset(),
  ],
  content: {
    pipeline: {
      include: [
        /\.(vue|svelte|[jt]sx|mdx?|html)($|\?)/,
        'src/**/*.{js,ts,jsx,tsx,mdx}',
      ],
    },
  },
});
```

---

## Configuration Options

### 1. `presets`
Presets bundle rules, shortcuts, variants, and theme defaults. By default, always include `nuicssPreset()`, which bundles the complete Nofinite token system, typography scales, and utility rules.

```ts
presets: [
  nuicssPreset({
    // optional preset configurations
  }),
],
```

### 2. `content.pipeline.include`
Specifies which source files the compiler should scan for class names. Use standard glob strings or regex patterns:

```ts
content: {
  pipeline: {
    include: [
      'src/**/*.{js,ts,jsx,tsx,mdx}',
      'components/**/*.{js,ts,jsx,tsx}',
      'pages/**/*.{js,ts,jsx,tsx}',
    ],
  },
},
```

### 3. `theme`
Extend the default color palette, font families, breakpoints, and sizing scales:

```ts
theme: {
  colors: {
    brand: {
      50: '#f0f9ff',
      500: '#0ea5e9',
      900: '#0c4a6e',
    },
  },
  breakpoints: {
    sm: '640px',
    md: '768px',
    lg: '1024px',
    xl: '1280px',
    '2xl': '1536px',
  },
},
```

### 4. `shortcuts`
Combine multiple utility classes into clean, reusable aliases or build domain-specific shortcuts on top of superclasses:

```ts
shortcuts: {
  'hero-heading': 'text-4xl font-extrabold tracking-tight lg:text-5xl text-default',
  'metric-badge': 'badge badge-subtle font-mono text-xs',
},
```

---


### Document: nuicss/ide-setup/page.mdx

# VS Code & Cursor IDE Setup

NUICSS provides first-class, **pure native IntelliSense** for VS Code, Cursor, and Windsurf directly through the built-in Language Server Protocol (LSP).

No third-party marketplace extensions are required. Once configured, your editor automatically provides instant class autocompletion, rich Markdown hover previews, and design token suggestions across HTML, JSX, TSX, Vue, and Svelte files.

---

## 1. Quick Setup (Automated CLI)

The easiest way to enable IntelliSense in any project is using the NUICSS CLI:

```bash
npx @nofinite/nuicss init
```

This one command automatically:
- Creates `nuicss.config.ts` if it doesn't already exist.
- Configures `.vscode/settings.json` with the native HTML and CSS custom data sets.

---

## 2. Manual Configuration

If you prefer to configure your editor manually, add the following to your project's `.vscode/settings.json`:

```json
{
  "html.customData": [
    "./node_modules/@nofinite/nuicss/dist/nuicss.html-data.json"
  ],
  "css.customData": [
    "./node_modules/@nofinite/nuicss/dist/nuicss.css-data.json"
  ]
}
```

> [!TIP]
> Both VS Code and Cursor read these files automatically. If you don't see autocomplete immediately after adding these settings, press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) and run **Developer: Reload Window**.

---

## 3. Features & Capabilities

### Instant Class Autocompletion
When typing `class="..."` or `className="..."` in HTML, JSX, TSX, Vue, or Svelte files, the editor dropdown displays all 50+ NUICSS superclasses:
- `btn`, `btn-primary`, `btn-secondary`, `btn-outline`, `btn-ghost`, `btn-danger`
- `card`, `card-responsive`, `metric-card`, `table-container`
- `input`, `textarea`, `select`, `switch`, `checkbox`
- `sparkline-container`, `sparkline-bar`, `progress-ring`, `metric-badge`
- Micro-interactions: `press-scale`, `hover-lift`, `glow-brand`, `skeleton-shimmer`

### Rich Hover Previews & Examples
Hovering over any NUICSS class name in your code displays:
- The component category (primitives, forms, overlays, widgets, charts).
- A concise description of its behavior and accessibility bindings.
- A drop-in HTML/JSX code example.
- The underlying atomic CSS utilities and OKLCH color rules.

### Design Token Autocomplete
In CSS, SCSS, or inline `style` attributes, typing `var(--` displays all NUICSS design tokens with their default values:
- Semantic backgrounds (`--bg-surface`, `--bg-subtle`, `--bg-page`)
- OKLCH action palettes (`--color-primary`, `--color-primary-hover`, `--color-danger`)
- Border radius tokens (`--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-full`)
- Spring easing functions (`--ease-spring`, `--ease-bounce`, `--ease-smooth`)

---

## 4. Why Native Custom Data?

| Feature | NUICSS Native Custom Data | Traditional Extensions |
| :--- | :--- | :--- |
| **Marketplace Download** | ❌ None (zero extension required) | ⚠️ Required from VS Code Marketplace |
| **Editor Support** | ✅ VS Code, Cursor, Windsurf, VSCodium | ⚠️ Often delayed or broken in forks |
| **Performance** | ⚡ Instant (handled by native editor LSP) | ⚠️ Background node process overhead |
| **Package Synchronization** | ✅ Instant on `npm update` | ⚠️ Wait for extension updates |

---


### Document: nuicss/installation/page.mdx

# Installation & Setup

Get started with **NUICSS** using your preferred framework, bundler, package manager, or zero-build CDN setup.

---

## 1. Package Installation

Install `@nofinite/nuicss` in your project:

```bash
# pnpm
pnpm add @nofinite/nuicss

# npm
npm install @nofinite/nuicss

# yarn
yarn add @nofinite/nuicss

# bun
bun add @nofinite/nuicss
```

---

## 2. Framework Integration

### A. Next.js (Turbopack & App Router)

NUICSS includes a first-class `withNuicss` Next.js plugin that automatically configures Turbopack aliases, package transpilation, and Webpack PostCSS pipelines:

```js
// next.config.mjs
import { withNuicss } from '@nofinite/nuicss/next';

/** @type {import('next').NextConfig} */
const nextConfig = {
  // your existing Next.js options
};

export default withNuicss(nextConfig);
```

Then import the precompiled stylesheet in your root layout:

```tsx
// app/layout.tsx
import '@nofinite/nuicss/styles.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className="bg-page text-default antialiased">
        {children}
      </body>
    </html>
  );
}
```

> [!TIP]
> `withNuicss` automatically resolves virtual CSS aliases for both Turbopack (`next dev --turbo` / Next.js 15 Turbopack) and Webpack without needing custom alias boilerplate in your configuration.

---

### B. Vite (React, Vue, Svelte)

For Vite-powered single-page applications, use `nuicssVitePlugin`. It provides on-demand utility compilation, live HMR, and zero PostCSS configuration:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nuicssVitePlugin } from '@nofinite/nuicss';

export default defineConfig({
  plugins: [
    react(),
    nuicssVitePlugin(),
  ],
});
```

Import the virtual stylesheet in your application entry point:

```ts
// src/main.tsx or src/index.ts
import '@nofinite/nuicss/virtual.css';
```

---

### C. PostCSS Pipeline (Astro, Webpack, Nuxt)

If you are using a standard PostCSS build pipeline, register the NUICSS PostCSS plugin:

```js
// postcss.config.mjs
export default {
  plugins: {
    '@nofinite/nuicss/postcss': {},
  },
};
```

Include the `@nuicss;` directive at the top of your global CSS:

```css
/* src/styles/global.css */
@nuicss;
```

---

### D. Standalone Precompiled CSS (Zero Compiler Setup)

If you prefer to consume NUICSS as standard precompiled CSS without running any build plugins or JIT compilers, import the pre-built stylesheet directly:

```ts
import '@nofinite/nuicss/styles.css';
```

This includes:
- Modern CSS reset and typography base
- OKLCH color palettes and semantic tokens (`--bg-page`, `--bg-surface`, `--color-primary`)
- All component superclasses (`btn`, `card`, `input`, `badge`, `table-container`, etc.)
- Dark mode theme switching rules

---

### E. Standalone CLI & Compiler (`nuicss`)

For non-Node stacks (Go, Python, PHP, Ruby) or standalone compilation workflows without a bundler plugin, use the official `nuicss` CLI:

```bash
# On-demand via npx
npx nuicss -i input.css -o dist/output.css --watch --minify

# Or install standalone binary (Zero Node.js required)
# Windows (PowerShell):
irm https://opensource.nofinite.com/nuicss/install.ps1 | iex

# macOS & Linux (Bash):
curl -fsSL https://opensource.nofinite.com/nuicss/install.sh | bash
```

See the complete [**NUICSS CLI Guide**](/nuicss/cli) for full command options, codebase linting (`nuicss check`), and automated migrations (`nuicss migrate`).

---

## 3. Zero-Build CDN Usage

For quick prototypes, HTML mockups, HTMX apps, or static server templates:

### Option A: JIT Runtime Script (Automatic On-the-Fly Compilation)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>NUICSS App</title>
  <script src="https://cdn.jsdelivr.net/npm/@nofinite/nuicss/dist/index.global.js"></script>
</head>
<body class="bg-page text-default p-8">
  
</body>
</html>
```

### Option B: Precompiled CSS

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nofinite/nuicss/dist/index.css" />
```

---

## 4. Configuration (`nuicss.config.ts`)

Create a `nuicss.config.ts` in your project root to extend themes, customize breakpoints, or register custom shortcuts:

```ts
// nuicss.config.ts
import { defineConfig, nuicssPreset } from '@nofinite/nuicss';

export default defineConfig({
  presets: [
    nuicssPreset() as any,
  ],
  content: {
    pipeline: {
      include: [
        /\.(vue|svelte|[jt]sx|mdx?|html)($|\?)/,
        'src/**/*.{js,ts,jsx,tsx,mdx}',
      ],
    },
  },
});
```

---

## Next Steps

- Explore [**Component Superclasses**](/nuicss/superclasses) for ready-to-use semantic classes (`btn`, `card`, `input`, `badge`).
- Learn how [**Theming & Design Tokens**](/nuicss/theming) leverage OKLCH and CSS variables for instant dark mode.
- Check out the interactive [**Theme Studio**](/nuicss/theme-studio) to customize your brand palette.

---


### Document: nuicss/llms/page.mdx

# LLMs.txt Documentation

How to get tools like Cursor, Windsurf, GitHub Copilot, ChatGPT, and Claude to understand `@nofinite/nuicss`.

> [!TIP]
> Looking for unified ecosystem presets or multi-package rules? Visit our central [AI Agents Hub](/ai).

We support **LLMs.txt** files for making `@nofinite/nuicss` design tokens and superclasses directly available to large language models.

---

## Directory Overview

The following machine-readable context files are available:

- [`/nuicss/llms.txt`](/nuicss/llms.txt): The main LLMs index for `@nofinite/nuicss`.
- [`/nuicss/llms-full.txt`](/nuicss/llms-full.txt): Complete context bundle containing all 120+ superclasses, OKLCH token variables, and utility classes.
- [`/llms.txt`](/llms.txt): Ecosystem index covering all 8 `@nofinite` libraries.
- [`/llms-full.txt`](/llms-full.txt): The unified ecosystem bundle.

---

## Usage with Cursor & Windsurf

Add `@nofinite/nuicss` context directly to your AI editor:

### 1. Cursor Docs Link
In Cursor Settings > Features > Docs, add:
```
https://opensource.nofinite.com/nuicss/llms-full.txt
```

### 2. Project Rule (`.cursorrules` or `.windsurfrules`)

```markdown
# NUICSS Rules for AI Assistants
1. Superclasses: Always prefer semantic superclasses (`btn`, `card`, `badge`, `input`, `table-container`, `kanban-board`, `markon-editor`, `chart-container`) over verbose Tailwind utility clusters.
2. OKLCH Design Tokens: Use OKLCH variables (`bg-surface`, `text-default`, `border-default`, `color-primary`). Never hardcode hex color literals (#...).
3. ARIA States: Use native ARIA attributes (`aria-selected="true"`, `aria-invalid="true"`, `aria-expanded="true"`) which NUICSS styles automatically.
4. Zero Downstream CSS Invariant: NUICSS is the sole styling engine. Downstream packages must never author, compile, or bundle independent CSS files.
```

---


### Document: nuicss/migration/page.mdx

# Tailwind & Legacy CSS Migration Guide

NUICSS includes an automated migration codemod that scans your HTML, JSX, TSX, Vue, Svelte, and Astro codebases and automatically refactors repetitive utility strings into elegant, maintainable NUICSS superclasses.

---

## Why Migrate to NUICSS Superclasses?

In standard utility-first CSS frameworks like Tailwind, components often suffer from **class name soup**:

```html
<!-- Messy Tailwind Utility Clutter -->
<button class="inline-flex items-center justify-center whitespace-nowrap gap-2 font-sans font-medium px-4 py-2 rounded-md bg-blue-600 text-white hover:bg-blue-700 active:scale-[0.98] transition-all text-sm disabled:opacity-50">
  Submit Payment
</button>
```

With NUICSS, the exact same visual design, OKLCH color accuracy, and micro-interactions collapse into two clean words:

```html
<!-- Clean, Maintainable NUICSS Superclass -->
<button class="btn btn-primary">
  Submit Payment
</button>
```

---

## 1. Automated CLI Migration

Run the NUICSS migration codemod directly in any project root using `npx`:

```bash
# Run interactive migration across your project
npx @nofinite/nuicss migrate

# Or run in dry-run mode to inspect changes without writing files
npx @nofinite/nuicss migrate --dry-run
```

The codemod scans your files (`src/**/*.{tsx,jsx,vue,svelte,astro,html}`) and performs pattern-matching replacements:

| Existing Utility Pattern | Automated NUICSS Superclass |
| --- | --- |
| `px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700` | `btn btn-primary` |
| `px-3 py-1 bg-gray-100 text-gray-900 border border-gray-200` | `btn btn-secondary` |
| `border border-gray-200 rounded-xl p-6 bg-white shadow-sm` | `card card-body` |
| `@container flex flex-col @sm:flex-row @sm:items-center` | `card-responsive` |
| `px-2.5 py-0.5 rounded-full text-xs font-semibold bg-blue-100 text-blue-700` | `badge badge-primary` |
| `h-9 w-full rounded-md border border-gray-300 bg-white px-3 py-1 text-sm` | `input` |
| `p-5 rounded-xl border border-gray-200 bg-white shadow-sm` | `metric-card` |
| `active:scale-[0.98] transition-transform duration-150 ease-out` | `press-scale` |
| `hover:-translate-y-1 hover:shadow-lg transition-all` | `hover-lift` |
| `animate-pulse bg-slate-200 rounded` | `skeleton-shimmer rounded` |
| `w-full overflow-x-auto rounded-xl border border-gray-200 bg-white shadow-sm` | `table-container` |

---

## 2. Drop-In Tailwind CDN Replacement

If you are prototyping or using Tailwind via CDN, you can replace the Tailwind script with NUICSS's one-link CDN:

```html
<!-- Before: Tailwind CDN -->
<script src="https://cdn.tailwindcss.com"></script>

<!-- After: NUICSS High-Performance CDN (All Tailwind utilities + 50+ superclasses) -->
<script src="https://cdn.jsdelivr.net/npm/@nofinite/nuicss@latest/dist/index.global.js"></script>
```

All Tailwind utilities (`flex`, `grid`, `gap-4`, `p-6`, `text-sm`) continue to work seamlessly, while superclasses (`btn`, `card`, `badge`, `metric-card`, `cq`) become immediately available with zero configuration.

---

## 3. Programmatic Migration API

You can also use the migration codemod programmatically in your build scripts:

```ts
import { migrateMarkupToNuicss } from '@nofinite/nuicss/migrate';

const legacyHtml = '<button class="px-4 py-2 bg-blue-600 text-white rounded-md">Save</button>';
const { result: modernHtml, replacementsCount } = migrateMarkupToNuicss(legacyHtml);
console.log(`Made ${replacementsCount} replacements:`, modernHtml);
// Output: Made 1 replacements: <button class="btn btn-primary">Save</button>
```

---


### Document: nuicss/page.mdx

<PackageHero packageId="nuicss" />

---

## Architectural Invariants

- **Single Source of Truth for Design Tokens & Styles:** `@nofinite/nuicss` is the sole source of truth for design tokens, OKLCH color palettes, and component superclasses across the entire ecosystem.
- **The Zero Downstream CSS Invariant:** Downstream packages (`NUI`, `Nofinite Kanban`, `Nofinite Markon`, `Nofinite Charts`, `Nofinite Media`, `Nofinite Locale`, `Nofinite Utils`) **MUST NEVER** author, compile, or bundle independent `.css` files. All component layouts, geometry, animations, drag-and-drop indicators, and token maps belong exclusively in `packages/nuicss`.
- **Universal Framework Agnostic Engine:** Fully compatible with plain HTML/CDN, Next.js (Turbopack & App Router), Vite (Vue, Svelte, React), SvelteKit, Astro, and backend template engines (HTMX, Go templates, Blade, ERB).

---

## Why NUICSS?

- **Component Superclasses**: Eliminates messy 15-class utility clusters with clean, semantic superclasses (`btn`, `card`, `input`, `badge`, `table-container`, `kanban-board`, `markon-editor`).
- **Instant On-Demand Compilation**: Powered by a high-speed JIT engine, compiling thousands of utility classes in milliseconds.
- **Turbopack & Next.js First-Class Support**: Includes `withNuicss` for seamless Turbopack alias resolution and zero-friction builds.
- **Perceptual OKLCH Design Tokens**: Harmonized design tokens (`bg-page`, `bg-surface`, `text-default`, `border-default`) for flawless dark mode transitions without color distortion.
- **Full Modern CSS Feature Set**: Supports arbitrary values (`w-[320px]`), variant grouping (`hover:(bg-primary text-white)`), responsive breakpoints (`sm:`, `md:`, `lg:`, `xl:`), and native CSS variables.

---

## Multi-Framework Usage

### 1. Plain HTML / CDN (Zero Build)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>NUICSS Vanilla App</title>
  <!-- Load NUICSS precompiled stylesheet or JIT script -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nofinite/nuicss/dist/index.css" />
</head>
<body class="bg-page text-default p-8">
  
</body>
</html>
```

### 2. Vue 3

```vue
<script setup lang="ts">
import '@nofinite/nuicss/styles.css';
</script>

<template>
  
</template>
```

### 3. Svelte 5

```svelte
<script lang="ts">
  import '@nofinite/nuicss/styles.css';
</script>


```

### 4. React & Next.js

```tsx
import React from 'react';
import '@nofinite/nuicss/styles.css';

export function CardExample() {
  return (
    
  );
}
```

---

## Core Sections

- [**Installation & Setup**](/nuicss/installation) — Add NUICSS to Next.js (Turbopack), Vite, or PostCSS projects.
- [**CLI & Standalone Compiler**](/nuicss/cli) — Standalone compilation, live file watching, codebase linting, and automated migrations.
- [**Component Superclasses**](/nuicss/superclasses) — Complete guide to `btn`, `card`, `input`, `badge`, and layout superclasses.
- [**Theming & Design Tokens**](/nuicss/theming) — Explore OKLCH tokens, semantic surfaces, and automatic dark mode.
- [**Theme Studio**](/nuicss/theme-studio) — Interactive sandbox to customize color palettes and preview components live.
- [**Configuration**](/nuicss/configuration) — Customize `nuicss.config.ts`, presets, and content scanning pipelines.
- [**Architecture & Engine**](/nuicss/architecture) — Learn how the JIT compiler, layers, and directives operate.
- [**Utilities Reference**](/nuicss/utilities/layout) — Comprehensive reference guides for layout, flexbox, grid, spacing, and typography.

---


### Document: nuicss/superclasses/page.mdx

# Component Superclasses

A comprehensive guide and reference to all pre-compiled component superclasses, semantic modifiers, and slot classes in **NUICSS**.

---

## The Single Source of Truth Philosophy

In modern web development, styling components with dozens of raw utility classes creates maintenance friction, inconsistency, and code bloat:

```html
<!-- ❌ Fragile Utility Cluster (14 classes to keep in sync everywhere) -->
<button class="inline-flex items-center justify-center px-4 py-2 text-sm font-medium rounded-md bg-blue-600 hover:bg-blue-700 text-white focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 transition-colors disabled:opacity-50 disabled:pointer-events-none shadow-sm">
  Submit
</button>

<!-- ✅ NUICSS Component Superclass (Semantic, accessible, and token-driven) -->
<button class="btn btn-primary">
  Submit
</button>
```

### Why Superclasses?
1. **Single Source of Truth:** `@nofinite/nuicss` defines your design tokens, OKLCH palettes, and component superclasses once. Both `@nofinite/nui` React components and raw HTML/CSS templates consume the exact same underlying CSS classes.
2. **Cascade Layer Safety (`@layer components`):** All superclasses are defined inside the CSS `@layer components` layer. You can override any style using atomic utility classes (`mt-4`, `w-full`, `opacity-75`) without requiring `!important`.
3. **Dual Syntax:** Every superclass supports two interchangeable naming conventions:
   - **Concise:** `btn`, `card`, `input`, `badge`, `modal`
   - **Namespace-Isolated:** `nui-btn`, `nui-card`, `nui-input`, `nui-badge`, `nui-modal`

---

## 1. Primitives

### Button (`btn`)

Interactive action elements with built-in active scaling, focus rings, and token-driven variants:

| Superclass | Description | Token Accent |
| :--- | :--- | :--- |
| `btn` | Base button structure, transitions, flex alignment | — |
| `btn-primary` | High-emphasis primary call-to-action | `var(--color-primary)` |
| `btn-default` | Standard secondary action with surface fill and border | `var(--bg-surface)`, `var(--border-default)` |
| `btn-outline` | Bordered button with transparent background | `var(--border-default)` |
| `btn-ghost` | Low-emphasis borderless button with hover highlight | `var(--bg-subtle)` |
| `btn-danger` | Destructive action button | `var(--color-danger)` |
| `btn-link` | Inline link styled button with text underline | `var(--color-primary)` |

**Sizes:** `btn-sm` (compact), `btn-md` (default), `btn-lg` (prominent), `btn-icon` (square 1:1 aspect ratio).  
**States:** `btn-loading` (displays animated indeterminate spinner).

```html

```

---

### Badge (`badge`)

Compact status chips, counts, and category indicators:

| Superclass | Semantic Role |
| :--- | :--- |
| `badge` | Base pill container with font scaling |
| `badge-primary` | Brand highlight badge |
| `badge-success` | Positive status (Active, Online, Completed) |
| `badge-warning` | Caution status (Pending, Review Required) |
| `badge-danger` | Critical status (Error, Failed, Terminated) |
| `badge-subtle` | Low-contrast neutral badge |

**Sizes & Modifiers:** `badge-sm`, `badge-md`, `badge-lg`, `badge-pill` (fully rounded), `badge-dot` (includes status bullet).

```html

```

---

### Card (`card`)

Surface container with automatic dark mode adaptation, subtle border, and rounded radius:

- Base: `card`
- Variants: `card-bordered` (accentuated border)
- Slots:
  - `card-header`: Top container with padding and flex alignment
  - `card-title`: Prominent card heading
  - `card-description`: Secondary supporting copy
  - `card-body`: Main content area
  - `card-footer`: Action or timestamp row with top border

```html

  
  
</div>
```

---

### Avatar (`avatar`)

Profile images with fallback monograms and presence indicators:

- Base: `avatar`
- Sizes: `avatar-sm`, `avatar-md`, `avatar-lg`, `avatar-xl`
- Shapes: `avatar-circle`, `avatar-square`
- Media: `avatar-image`
- Status Bullets: `avatar-online`, `avatar-busy`, `avatar-away`
- Stack: `avatar-group` (negative margin overlapping list)

---

### Kbd (`kbd`)

Keyboard shortcut key indicators with subtle bottom shadow and border:

- Base: `kbd`
- Sizes: `kbd-sm`, `kbd-md`, `kbd-lg`

```html

```

---

### Spinner & Skeleton

Asynchronous loading state indicators:

- **Spinner:** `spinner`, `spinner-sm`, `spinner-md`, `spinner-lg`, `spinner-primary`
- **Skeleton:** `skeleton`, `skeleton-text`, `skeleton-circle`, `skeleton-rect`

---

## 2. Form Superclasses

### Input & Textarea (`input`, `textarea`)

Form fields with focus rings, placeholder styling, and error states:

| Superclass | Purpose |
| :--- | :--- |
| `input` | Base single-line input field |
| `input-sm` / `input-lg` | Size scale adjustments |
| `input-error` | Validation error styling (border token: `var(--color-danger)`) |
| `input-group` | Container for attaching prefix/suffix addons |
| `input-addon-left` / `input-addon-right` | Attached addon icons or currency badges |
| `textarea` | Multi-line text input |
| `textarea-error` | Validation error styling for textareas |

```html

```

---

### Checkbox, Radio, and Switch

Selection controls built with accessible contrast and native interaction:

- **Checkbox:** `checkbox`, `checkbox-sm`, `checkbox-md`, `checkbox-lg`, `checkbox-label`
- **Radio:** `radio`, `radio-group`, `radio-group-horizontal`, `radio-label`
- **Switch:** `switch`, `switch-thumb`, `switch-label`

---

## 3. Overlay Superclasses

### Modal & Dialog (`modal`, `dialog`)

Backdrop overlays, centered boxes, and animated dialogs:

- Modal Base: `modal` (backdrop overlay with blur)
- Content Box: `modal-box`, `modal-sm`, `modal-md`, `modal-lg`, `modal-xl`, `modal-full`
- Slots: `modal-header`, `modal-title`, `modal-description`, `modal-body`, `modal-footer`, `modal-close`
- Dialog Variants: `dialog`, `dialog-box`, `dialog-icon`, `dialog-icon-danger`, `dialog-icon-warning`, `dialog-icon-success`

---

### Drawer (`drawer`)

Off-canvas sheets sliding from screen boundaries:

- Base: `drawer`
- Placements: `drawer-right`, `drawer-left`, `drawer-top`, `drawer-bottom`
- Content: `drawer-box`, `drawer-header`, `drawer-title`, `drawer-body`, `drawer-footer`, `drawer-close`

---

### Tooltip & Popover (`tooltip`, `popover`)

Descriptive popups with automatic boundary safety:

- **Tooltip:** `tooltip`, `tooltip-top`, `tooltip-bottom`, `tooltip-left`, `tooltip-right`, `tooltip-arrow`
- **Popover:** `popover-wrapper`, `popover-content`, `popover-header`, `popover-body`, `popover-close`

---

## 4. Widget Superclasses

### Table (`table-container`, `table`)

Responsive data table wrapper with zebra striping and sticky headers:

- `table-container`: Horizontal scrolling wrapper with border and radius
- `table`: Base table layout
- `table-head`, `table-header`, `table-th`: Header rows and cells
- `table-body`, `table-row`, `table-cell`: Body rows and data cells
- `table-sortable`: Interactive sortable column header styling

```html

```

---

### Tabs & Stepper

- **Tabs:** `tabs`, `tab-list`, `tab-list-pills`, `tab`, `tab-pill`, `tab-panel`
- **Stepper:** `stepper`, `step`, `step-indicator`, `step-content`, `step-title`, `step-connector`

---

## 5. Media & Navigation

- **Breadcrumbs:** `breadcrumbs`, `breadcrumb-list`, `breadcrumb-item`, `breadcrumb-separator`, `breadcrumb-active`
- **Pagination:** `pagination`, `pagination-item`, `pagination-prev`, `pagination-next`, `pagination-ellipsis`
- **MegaMenu:** `mega-menu`, `mega-menu-trigger`, `mega-menu-content`, `mega-menu-column`, `mega-menu-link`
- **Code Block:** `code-block`, `code-header`, `code-lang`, `code-copy-btn`, `code-pre`

---

## Best Practices

### Do
- Always use `btn`, `card`, `input`, `badge`, etc. as your starting base styles rather than composing raw utility clusters.
- Apply utility classes on top of superclasses for contextual spacing (`mt-6`, `gap-4`, `w-full`).
- Rely on semantic variants (`btn-primary`, `badge-success`, `input-error`) so themes adapt automatically in dark mode.

### Don't
- Do not write hardcoded hex color values (`bg-[#1d4ed8]`); use semantic classes (`btn-primary` or `bg-primary`).
- Never use `!important` to override superclass padding or borders; since superclasses reside in `@layer components`, utilities will naturally take precedence.

---


### Document: nuicss/theming/page.mdx

# Theming & Design Tokens

NUICSS features a modern, token-first design system built on **OKLCH perceptual color palettes** and CSS custom properties. It functions as the single source of truth for `@nofinite/nui` and `@nofinite/nuicss`.

---

## Why OKLCH?

Unlike legacy sRGB or HSL color spaces, **OKLCH (Oklab Lightness Chroma Hue)** is perceptually uniform. This means:
1. **Predictable Contrast:** A lightness value of `0.6` in green has the exact same perceived brightness as `0.6` in blue or red, preventing contrast violations when customizing brand palettes.
2. **Smooth Gradients:** Color interpolations stay vibrant and never pass through muddy grayish dead zones.
3. **Wide Gamut:** Supports display-P3 screens natively while providing safe fallbacks for legacy browsers.

---

## Semantic Color Tokens

NUICSS components and utility classes consume semantic variables that invert seamlessly between light and dark modes:

| Semantic Class | CSS Variable | Light Mode Role | Dark Mode Role |
| :--- | :--- | :--- | :--- |
| `bg-page` | `var(--bg-page)` | Canvas background (neutral-50) | Dark canvas (neutral-950) |
| `bg-surface` | `var(--bg-surface)` | Card and modal container (white) | Elevated dark surface (neutral-900) |
| `bg-subtle` | `var(--bg-subtle)` | Hover highlights and secondary tiles | Subtle dark tile (neutral-800) |
| `bg-muted` | `var(--bg-muted)` | Inactive pills, disabled fills | Muted dark background (neutral-800) |
| `text-default` | `var(--fg-default)` | High-contrast primary headings and body | Crisp white / light gray text |
| `text-muted` | `var(--fg-muted)` | Secondary captions and helper notes | Medium contrast text |
| `border-default` | `var(--border-default)`| Structural boundaries and cards | Subtle dark borders |
| `border-subtle` | `var(--border-subtle)` | Table cell dividers, secondary rules | Low-contrast dark dividers |

---

## Brand & Feedback Tokens

| Role | Background | Text Utility | Border Utility | Purpose |
| :--- | :--- | :--- | :--- | :--- |
| **Primary** | `bg-primary` | `text-primary` | `border-primary` | Main brand action and active states |
| **Success** | `bg-success` | `text-success` | `border-success` | Confirmed operations, positive trends |
| **Warning** | `bg-warning` | `text-warning` | `border-warning` | Non-blocking alerts, cautionary statuses |
| **Danger** | `bg-danger` | `text-danger` | `border-danger` | Destructive actions, system errors |

---

## Data Visualization & Chart Tokens

All charts in `@nofinite/nui` automatically read these 5 sequential theme tokens for multi-series graphs:

| Token | Variable | Purpose |
| :--- | :--- | :--- |
| Chart 1 | `var(--chart-1)` | Primary data series / brand stroke |
| Chart 2 | `var(--chart-2)` | Secondary series comparison |
| Chart 3 | `var(--chart-3)` | Tertiary series |
| Chart 4 | `var(--chart-4)` | Fourth series metric |
| Chart 5 | `var(--chart-5)` | Fifth series / auxiliary data |

---

## Border Radius Scale

NUICSS standardizes curvature using geometric radius tokens:

| Utility Class | CSS Variable | Computed Value | Recommended Use |
| :--- | :--- | :--- | :--- |
| `rounded-sm` | `var(--radius-sm)` | `4px` | Small badges, tooltips, tags |
| `rounded-md` | `var(--radius-md)` | `8px` | Buttons, inputs, small cards |
| `rounded-lg` | `var(--radius-lg)` | `12px` | Standard cards, modal dialogs, menus |
| `rounded-xl` | `var(--radius-xl)` | `16px` | Hero feature sections, large callouts |
| `rounded-full` | `var(--radius-full)` | `9999px` | Avatar circles, pill badges |

---

## Dark Mode Implementation

NUICSS applies dark mode styles by toggling the `.dark` class on the root `<html>` element:

```html
<!-- Light Mode -->
<html class="light">
  <body class="bg-page text-default">...</body>
</html>

<!-- Dark Mode -->
<html class="dark">
  <body class="bg-page text-default">...</body>
</html>
```

Because all component superclasses (`btn`, `card`, `input`, `table`) use CSS variables for their fills and borders, toggling the root class instantly switches themes without requiring utility class duplication (e.g. `bg-white dark:bg-slate-900`).

---

## Customizing Your Theme

To override any token globally, simply redefine the CSS variable in your stylesheet:

```css
/* app/globals.css */
:root {
  /* Customize brand primary to a custom violet OKLCH color */
  --brand-primary: oklch(0.55 0.22 280);
  --color-primary: var(--brand-primary);
  
  /* Make standard card corners sharper */
  --radius-lg: 6px;
}
```

> [!TIP]
> Use the [**Theme Studio**](/nuicss/theme-studio) to visually customize palettes, test contrast ratios, and export ready-to-use CSS configurations.

---


### Document: nuicss/utilities/backgrounds-borders/page.mdx

# Backgrounds & Borders Utilities

Utilities for styling backgrounds, borders, divide lines, outline rings, and corner radii.

---

## Background Colors

NUICSS provides semantic background utilities that dynamically adapt to theme changes:

| Class | Properties |
| --- | --- |
| `bg-page` | `background-color: var(--bg-page);` |
| `bg-surface` | `background-color: var(--bg-surface);` |
| `bg-subtle` | `background-color: var(--bg-subtle);` |
| `bg-muted` | `background-color: var(--bg-muted);` |
| `bg-primary` | `background-color: var(--color-primary);` |
| `bg-transparent` | `background-color: transparent;` |
| `bg-white` | `background-color: #ffffff;` |
| `bg-black` | `background-color: #000000;` |

---

## Border Width & Style

| Class | Properties |
| --- | --- |
| `border` | `border-width: 1px; border-style: solid;` |
| `border-0` | `border-width: 0px;` |
| `border-2` | `border-width: 2px; border-style: solid;` |
| `border-4` | `border-width: 4px; border-style: solid;` |
| `border-dashed` | `border-style: dashed;` |
| `border-dotted` | `border-style: dotted;` |

---

## Border Colors

| Class | Properties |
| --- | --- |
| `border-default` | `border-color: var(--border-default);` |
| `border-subtle` | `border-color: var(--border-subtle);` |
| `border-primary` | `border-color: var(--color-primary);` |
| `border-transparent` | `border-color: transparent;` |

---

## Border Radius

| Class | Properties |
| --- | --- |
| `rounded-none` | `border-radius: 0px;` |
| `rounded-sm` | `border-radius: var(--radius-sm, 4px);` |
| `rounded` | `border-radius: 0.25rem;` |
| `rounded-md` | `border-radius: var(--radius-md, 8px);` |
| `rounded-lg` | `border-radius: var(--radius-lg, 12px);` |
| `rounded-xl` | `border-radius: var(--radius-xl, 16px);` |
| `rounded-full` | `border-radius: 9999px;` |

---


### Document: nuicss/utilities/effects-filters/page.mdx

# Effects & Filters Utilities

Utilities for applying drop shadows, opacity, backdrop blurs, transitions, and animations in NUICSS.

---

## Box Shadow

| Class | Properties |
| --- | --- |
| `shadow-none` | `box-shadow: none;` |
| `shadow-xs` | `box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);` |
| `shadow-sm` | `box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);` |
| `shadow` | `box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);` |
| `shadow-md` | `box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);` |
| `shadow-lg` | `box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1);` |
| `shadow-xl` | `box-shadow: 0 20px 25px -5px rgb(0 0 0 / 0.1);` |

---

## Opacity

| Class | Properties |
| --- | --- |
| `opacity-0` | `opacity: 0;` |
| `opacity-25` | `opacity: 0.25;` |
| `opacity-50` | `opacity: 0.5;` |
| `opacity-75` | `opacity: 0.75;` |
| `opacity-90` | `opacity: 0.9;` |
| `opacity-100` | `opacity: 1;` |

---

## Backdrop Blur

| Class | Properties |
| --- | --- |
| `backdrop-blur-none` | `backdrop-filter: blur(0);` |
| `backdrop-blur-sm` | `backdrop-filter: blur(4px);` |
| `backdrop-blur` | `backdrop-filter: blur(8px);` |
| `backdrop-blur-md` | `backdrop-filter: blur(12px);` |
| `backdrop-blur-lg` | `backdrop-filter: blur(16px);` |

---

## Transitions & Animation

| Class | Properties |
| --- | --- |
| `transition` | `transition-property: color, background-color, border-color, text-decoration-color, fill, stroke, opacity, box-shadow, transform, filter, backdrop-filter;` |
| `transition-colors` | `transition-property: color, background-color, border-color;` |
| `transition-opacity` | `transition-property: opacity;` |
| `transition-transform` | `transition-property: transform;` |
| `duration-150` | `transition-duration: 150ms;` |
| `duration-200` | `transition-duration: 200ms;` |
| `duration-300` | `transition-duration: 300ms;` |
| `ease-in-out` | `transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);` |
| `animate-spin` | `animation: spin 1s linear infinite;` |
| `animate-pulse` | `animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;` |

---


### Document: nuicss/utilities/flex-grid/page.mdx

# Flexbox & Grid Utilities

Utilities for building 1D and 2D responsive layouts using CSS Flexbox and CSS Grid.

---

## Flex Direction & Wrapping

| Class | Properties |
| --- | --- |
| `flex-row` | `flex-direction: row;` |
| `flex-row-reverse` | `flex-direction: row-reverse;` |
| `flex-col` | `flex-direction: column;` |
| `flex-col-reverse` | `flex-direction: column-reverse;` |
| `flex-wrap` | `flex-wrap: wrap;` |
| `flex-nowrap` | `flex-wrap: nowrap;` |
| `flex-wrap-reverse` | `flex-wrap: wrap-reverse;` |

---

## Justify Content & Alignment

| Class | Properties |
| --- | --- |
| `justify-start` | `justify-content: flex-start;` |
| `justify-center` | `justify-content: center;` |
| `justify-end` | `justify-content: flex-end;` |
| `justify-between` | `justify-content: space-between;` |
| `justify-around` | `justify-content: space-around;` |
| `items-start` | `align-items: flex-start;` |
| `items-center` | `align-items: center;` |
| `items-end` | `align-items: flex-end;` |
| `items-stretch` | `align-items: stretch;` |

---

## Grid Columns & Rows

| Class | Properties |
| --- | --- |
| `grid-cols-1` | `grid-template-columns: repeat(1, minmax(0, 1fr));` |
| `grid-cols-2` | `grid-template-columns: repeat(2, minmax(0, 1fr));` |
| `grid-cols-3` | `grid-template-columns: repeat(3, minmax(0, 1fr));` |
| `grid-cols-4` | `grid-template-columns: repeat(4, minmax(0, 1fr));` |
| `grid-cols-6` | `grid-template-columns: repeat(6, minmax(0, 1fr));` |
| `grid-cols-12` | `grid-template-columns: repeat(12, minmax(0, 1fr));` |

---

## Gap

Control gutters between grid and flex items:

| Class | Properties |
| --- | --- |
| `gap-1` | `gap: 0.25rem;` |
| `gap-2` | `gap: 0.5rem;` |
| `gap-3` | `gap: 0.75rem;` |
| `gap-4` | `gap: 1rem;` |
| `gap-6` | `gap: 1.5rem;` |
| `gap-8` | `gap: 2rem;` |
| `gap-x-4` | `column-gap: 1rem;` |
| `gap-y-4` | `row-gap: 1rem;` |

---


### Document: nuicss/utilities/layout/page.mdx

# Layout Utilities

Utilities for controlling page layout, element display, positioning, and box model structure in NUICSS.

---

## Display

Control the display property of elements:

| Class | Properties |
| --- | --- |
| `block` | `display: block;` |
| `inline-block` | `display: inline-block;` |
| `inline` | `display: inline;` |
| `flex` | `display: flex;` |
| `inline-flex` | `display: inline-flex;` |
| `grid` | `display: grid;` |
| `inline-grid` | `display: inline-grid;` |
| `hidden` | `display: none;` |

---

## Position

Control element positioning in the DOM:

| Class | Properties |
| --- | --- |
| `static` | `position: static;` |
| `fixed` | `position: fixed;` |
| `absolute` | `position: absolute;` |
| `relative` | `position: relative;` |
| `sticky` | `position: sticky;` |

### Inset & Placement

| Class | Properties |
| --- | --- |
| `inset-0` | `top: 0; right: 0; bottom: 0; left: 0;` |
| `top-0` | `top: 0;` |
| `right-0` | `right: 0;` |
| `bottom-0` | `bottom: 0;` |
| `left-0` | `left: 0;` |

---

## Z-Index

Stacking order utilities:

| Class | Properties |
| --- | --- |
| `z-0` | `z-index: 0;` |
| `z-10` | `z-index: 10;` |
| `z-20` | `z-index: 20;` |
| `z-30` | `z-index: 30;` |
| `z-40` | `z-index: 40;` |
| `z-50` | `z-index: 50;` |
| `z-auto` | `z-index: auto;` |

---

## Overflow

Control how content behaves when it exceeds its container:

| Class | Properties |
| --- | --- |
| `overflow-auto` | `overflow: auto;` |
| `overflow-hidden` | `overflow: hidden;` |
| `overflow-visible` | `overflow: visible;` |
| `overflow-scroll` | `overflow: scroll;` |
| `overflow-x-auto` | `overflow-x: auto;` |
| `overflow-y-auto` | `overflow-y: auto;` |

---


### Document: nuicss/utilities/sizing/page.mdx

# Sizing Utilities

Utilities for setting element width, height, min/max dimensions, and aspect ratios.

---

## Width

| Class | Properties |
| --- | --- |
| `w-auto` | `width: auto;` |
| `w-full` | `width: 100%;` |
| `w-screen` | `width: 100vw;` |
| `w-1/2` | `width: 50%;` |
| `w-1/3` | `width: 33.333333%;` |
| `w-2/3` | `width: 66.666667%;` |
| `w-1/4` | `width: 25%;` |
| `w-3/4` | `width: 75%;` |
| `w-16` | `width: 4rem;` |
| `w-32` | `width: 8rem;` |
| `w-64` | `width: 16rem;` |

---

## Height

| Class | Properties |
| --- | --- |
| `h-auto` | `height: auto;` |
| `h-full` | `height: 100%;` |
| `h-screen` | `height: 100vh;` |
| `h-16` | `height: 4rem;` |
| `h-32` | `height: 8rem;` |
| `h-64` | `height: 16rem;` |

---

## Min & Max Sizing

| Class | Properties |
| --- | --- |
| `min-w-0` | `min-width: 0px;` |
| `min-w-full` | `min-width: 100%;` |
| `max-w-xs` | `max-width: 20rem;` |
| `max-w-sm` | `max-width: 24rem;` |
| `max-w-md` | `max-width: 28rem;` |
| `max-w-lg` | `max-width: 32rem;` |
| `max-w-xl` | `max-width: 36rem;` |
| `max-w-full` | `max-width: 100%;` |
| `min-h-screen` | `min-height: 100vh;` |
| `max-h-full` | `max-height: 100%;` |

---


### Document: nuicss/utilities/spacing/page.mdx

# Spacing Utilities

Utilities for controlling padding, margin, and space between elements using the 4px baseline scale.

---

## Padding

| Class | Properties |
| --- | --- |
| `p-0` | `padding: 0px;` |
| `p-1` | `padding: 0.25rem; /* 4px */` |
| `p-2` | `padding: 0.5rem;  /* 8px */` |
| `p-3` | `padding: 0.75rem; /* 12px */` |
| `p-4` | `padding: 1rem;    /* 16px */` |
| `p-6` | `padding: 1.5rem;  /* 24px */` |
| `p-8` | `padding: 2rem;    /* 32px */` |
| `p-12` | `padding: 3rem;   /* 48px */` |

### Directional Padding
- `px-4` — horizontal padding (`left` & `right`)
- `py-2` — vertical padding (`top` & `bottom`)
- `pt-4`, `pr-4`, `pb-4`, `pl-4` — individual sides

---

## Margin

| Class | Properties |
| --- | --- |
| `m-0` | `margin: 0px;` |
| `m-auto` | `margin: auto;` |
| `mx-auto` | `margin-left: auto; margin-right: auto;` |
| `m-2` | `margin: 0.5rem;` |
| `m-4` | `margin: 1rem;` |
| `m-8` | `margin: 2rem;` |

### Negative Margins
Prefix any margin utility with a dash to apply negative spacing:
- `-m-2` (`margin: -0.5rem;`)
- `-mt-4` (`margin-top: -1rem;`)
- `-mx-6` (`margin-left: -1.5rem; margin-right: -1.5rem;`)

---

## Arbitrary Values

NUICSS supports any arbitrary spacing value using square bracket notation:

```html

```

---


### Document: nuicss/utilities/typography/page.mdx

# Typography Utilities

Utilities for font sizing, font weights, line heights, text alignment, and typography styling.

---

## Font Size

| Class | Font Size | Line Height |
| --- | --- | --- |
| `text-xs` | `0.75rem (12px)` | `1rem (16px)` |
| `text-sm` | `0.875rem (14px)` | `1.25rem (20px)` |
| `text-base` | `1rem (16px)` | `1.5rem (24px)` |
| `text-lg` | `1.125rem (18px)` | `1.75rem (28px)` |
| `text-xl` | `1.25rem (20px)` | `1.75rem (28px)` |
| `text-2xl` | `1.5rem (24px)` | `2rem (32px)` |
| `text-3xl` | `1.875rem (30px)` | `2.25rem (36px)` |
| `text-4xl` | `2.25rem (36px)` | `2.5rem (40px)` |

---

## Font Weight

| Class | Properties |
| --- | --- |
| `font-thin` | `font-weight: 100;` |
| `font-light` | `font-weight: 300;` |
| `font-normal` | `font-weight: 400;` |
| `font-medium` | `font-weight: 500;` |
| `font-semibold` | `font-weight: 600;` |
| `font-bold` | `font-weight: 700;` |
| `font-extrabold` | `font-weight: 800;` |

---

## Text Alignment & Transform

| Class | Properties |
| --- | --- |
| `text-left` | `text-align: left;` |
| `text-center` | `text-align: center;` |
| `text-right` | `text-align: right;` |
| `uppercase` | `text-transform: uppercase;` |
| `lowercase` | `text-transform: lowercase;` |
| `capitalize` | `text-transform: capitalize;` |
| `truncate` | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap;` |

---