[!WARNING] IMPORTANT: Installation via NPX is required (Do not use npm install).

Run npx gladvn init instead.

gladvn is a CLI-first React component library built on top of Base UI and Tailwind CSS v4. We do not distribute components via npm for you to import blindly. Instead, you run a command to scaffold the source code directly into your project.

You own the code. You own the abstractions.

✨ The Problem We Solve: Micro/Macro Architecture

Most UI libraries force a choice:

• Too primitive: You have to build everything yourself from scratch.
• Too opinionated: You get locked into their design choices and fight the defaults.

gladvn solves this with a strict Micro/Macro architecture.

• Micro Components (Primitives): Dumb, stateless building blocks. You control 100% of the assembly.
• Macro Components (Presets): Smart, pre-configured compositions of micro components. Drop them in and move fast.

Both use the exact same design system.

// Micro — Assemble it your way
import { Button } from "@gladvn/components/micro/button";

<Button variant="solid" color="primary">Submit</Button>


// Macro — Ready-to-use presets
import { InputPreset } from "@gladvn/components/macro/input-preset";

<InputPreset label="Email" error={errors.email} />

🚀 Features

• 45 Color/Variant Combinations: 9 semantic colors × 5 variants (solid, outline, ghost, soft, link) out of the box.
• Zero-Portal Theming: Modals and Popovers automatically inherit your theme without manual ThemeWrapper headaches.
• Base UI Powered: Built on MUI's next-generation headless UI library.
• AI-First Design: Includes llms.txt and semantic data-attributes designed specifically for AI coding agents (Cursor, Copilot, Claude).
• Smart Dependency Install: The CLI scans your copied code and only installs the npm packages you actually use.

📦 Installation

Do NOT run npm install gladvn. This is a CLI tool designed to copy source code directly into your project.

Prerequisites

Before running the CLI, ensure your project meets the following requirements:

• React 19 / Next.js (App Router or Vite)
• Tailwind CSS v4 installed and configured
• pnpm (recommended), npm, or yarn

Setup

Run the following command in your React/Next.js project to initialize gladvn and copy the components to your local repository:

npx gladvn init

The CLI will launch an interactive session:

1. Ask for the path to your global CSS file.
2. Provide a Checkbox Menu for you to select exactly which components you want to install. Use <space> to select and <enter> to confirm.
3. Copy the selected source code and core utilities into your project (default: ./gladvn/).
4. Inject Tailwind CSS configurations.
5. Automatically scan your copied code and only install the npm packages you actually use.

🆚 Comparison

| Feature | gladvn | shadcn/ui | MUI | |---------|-----------|-----------|-----| | Installation | npx gladvn init | npx shadcn@latest init | npm install @mui/material | | Own your code | ✅ Yes | ✅ Yes | ❌ npm dependency | | Micro/Macro Architecture | ✅ Yes | ❌ No | ⚠️ Partial | | Semantic colors | ✅ 9 colors | ⚠️ 2 colors | ✅ Extensive | | Zero-portal theming | ✅ Automatic | ❌ Manual | ✅ ThemeProvider | | Headless UI | Base UI | Radix UI | Own | | AI coding guidelines | ✅ llms.txt | ❌ No | ❌ No |

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to set up your environment, write components, and submit Pull Requests.

Please adhere to our Code of Conduct.

📄 License

This project is licensed under the MIT License.