npm package: @livx.cc/bare-v2
Description: Shadcn-inspired minimalist CSS library with semantic, LLM-friendly class names
Author: livz
Latest version: 2.2.2

# @livx.cc/bare-v2

> Shadcn-inspired minimalist CSS library with semantic, LLM-friendly class names

**bare-v2** is a modern CSS library designed for both human developers and AI assistants. It combines the elegant design principles of Shadcn with semantic class naming that makes it easy for LLMs to generate consistent, beautiful UIs.

### Philosophy
**bare-v2** is a CSS-first, semantic, LLM-friendly design system. It favors *meaningful class names over cryptic utility chains*, *layered composition over duplication*, and *progressive enhancement over heavy JavaScript*. The public authoring model is organized into four primary layers (with design atoms implicitly powering them):
- **Atoms** (lowest public layer) are low-level layout primitives (flex, grid, stack, spacer) without implying meaning.
- **Primitives** are semantic UI components (buttons, cards, alerts) built from atoms.
- **Patterns** assemble primitives into common structural or marketing compositions with BEM-style modifiers.
- **Utilities** offer focused, single-responsibility helpers (responsive visibility, gradients, prose) and must not re-implement patterns.

Core principles:
1. **Semantic First** – Class names describe intent (e.g., `card-elevated`, `btn-destructive`) so both humans and AI can reason about composition.
2. **Layer Discipline** – Higher layers never leak raw design decisions—tokens flow upward; no hard-coded magic values in patterns.
3. **Minimal JavaScript** – Only where interaction, accessibility, or state genuinely requires it (dropdowns, toasts, navigation). Everything else is pure CSS.
4. **Composable > Variant Explosion** – Prefer a few strong primitives + light modifiers over fleets of one-off variants.
5. **Dark Mode by Design** – Theme toggling requires no class churn—semantic colors adapt automatically via `.dark` or `data-theme="dark"`.
6. **LLM Friendly** – Naming optimized so AI can generate correct markup without memorizing internals.
7. **Refactor Friendly** – Each layer has a clear dependency boundary; changes propagate predictably.

This philosophy keeps the system lean, expressive, and resilient as new features are layered in.

> Taxonomy summary (public): Atoms → Primitives → Patterns → Utilities. (Internal foundation: design tokens). See `LLM.md` for exhaustive reference, usage checklists, and decision guides.

## ✨ Key Features

- **🎨 Shadcn-inspired Design**: Subtle shadows, refined borders, elegant typography
- **🤖 LLM-Friendly**: Semantic class names like `.btn-destructive`, `.card-elevated`
- **🌗 Dark Mode Native**: Built-in dark mode with `.dark` class
- **📦 Modular Architecture**: Import only what you need via LESS
- **🔧 Tailwind Integration**: Uses Tailwind utilities with `bare-` prefix to avoid conflicts
- **🎯 Zero Conflicts**: All Tailwind classes prefixed, won't interfere with your project
- **📱 Responsive**: Mobile-first with intuitive responsive utilities

## 🚀 Quick Start

### CDN Usage (Fastest)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <!-- bare-v2 core CSS -->
  <link rel="stylesheet" href="https://unpkg.com/@livx.cc/bare-v2/dist/bare.css">
  
  <!-- Optional: Font Awesome for icons -->
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css" crossorigin="anonymous" referrerpolicy="no-referrer">
</head>
<body>
  <div class="card">
    <div class="card-header">
      <h3 class="card-title">Hello World</h3>
    </div>
    <div class="card-content">
      <p>Your first bare-v2 component!</p>
      <button class="btn btn-default">Click Me</button>
    </div>
  </div>
</body>
</html>
```

### NPM Installation

```bash
# Using bun (recommended)
bun add @livx.cc/bare-v2

# Using npm
npm install @livx.cc/bare-v2

# Using yarn
yarn add @livx.cc/bare-v2
```

### Import Full CSS

```css
/* In your main CSS file */
@import '@livx.cc/bare-v2/dist/bare.css';
```

### Modular LESS Imports

```less
// Import only tokens (design system variables)
@import '@livx.cc/bare-v2/less/tokens';

// Import specific layers
@import '@livx.cc/bare-v2/less/atoms';       // Layout primitives (flex, grid)
@import '@livx.cc/bare-v2/less/primitives';  // Components (button, card, input)
@import '@livx.cc/bare-v2/less/patterns';    // Layout structures
@import '@livx.cc/bare-v2/less/utilities';   // Helper classes

// Or import everything
@import '@livx.cc/bare-v2/less';
```

## 🎯 Core Components

### Buttons

```html
<!-- Variants -->
<button class="btn btn-default">Default</button>
<button class="btn btn-secondary">Secondary</button>
<button class="btn btn-destructive">Delete</button>
<button class="btn btn-outline">Outline</button>
<button class="btn btn-ghost">Ghost</button>
<button class="btn btn-subtle">Subtle</button>
<button class="btn btn-subtle active">Subtle (Active)</button>
<button class="btn btn-link">Link</button>

<!-- Sizes -->
<button class="btn btn-default btn-sm">Small</button>
<button class="btn btn-default">Default</button>
<button class="btn btn-default btn-lg">Large</button>

### Icons

Font Awesome 6.5.2 is supported with size utilities. First include Font Awesome:
```html
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css" crossorigin="anonymous" referrerpolicy="no-referrer">
```

Then use the icons with size utilities:
```html
<!-- Icon sizes -->
<i class="fa-solid fa-star icon-xs"></i>
<i class="fa-solid fa-star icon-sm"></i>
<i class="fa-solid fa-star icon-md"></i>
<i class="fa-solid fa-star icon-lg"></i>
<i class="fa-solid fa-star icon-xl"></i>
<i class="fa-solid fa-star icon-2xl"></i>
<i class="fa-solid fa-star icon-3xl"></i>
<i class="fa-solid fa-star icon-4xl"></i>

<!-- Icon button -->
<button class="btn btn-icon btn-default">
  <i class="fa-solid fa-magnifying-glass"></i>
</button>

<!-- States -->
<button class="btn btn-default" disabled>Disabled</button>
<button class="btn btn-default btn-loading">Loading...</button>
```

### Cards

```html
<!-- Basic card -->
<div class="card">
  <div class="card-header">
    <h3 class="card-title">Card Title</h3>
    <p class="card-description">Optional description</p>
  </div>
  <div class="card-content">
    <p>Card content goes here</p>
  </div>
  <div class="card-footer">
    <button class="btn btn-outline btn-sm">Action</button>
  </div>
</div>

<!-- Card variants -->
<div class="card card-elevated">Enhanced shadow</div>
<div class="card card-interactive">Clickable with hover effect</div>
<div class="card card-bordered">2px border, no shadow</div>
<div class="card card-ghost">No border or shadow</div>
```

### Form Controls

```html
<!-- Basic input with label -->
<div class="form-group">
  <label class="label">Email Address</label>
  <input type="email" class="input" placeholder="you@example.com">
  <span class="form-help">We'll never share your email</span>
</div>

<!-- Input variants -->
<input class="input input-outlined" placeholder="Outlined variant">
<input class="input input-borderless" placeholder="Borderless variant">
<input class="input input-error" placeholder="Error state">
<input class="input input-warning" placeholder="Warning state">
<input class="input input-success" placeholder="Success state">

<!-- Input states -->
<input class="input" disabled placeholder="Disabled input">
<input class="input" readonly value="Read only">
<input class="input input-loading" placeholder="Loading...">

<!-- Input sizes -->
<input class="input input-sm" placeholder="Small">
<input class="input" placeholder="Default">
<input class="input input-lg" placeholder="Large">

<!-- Input groups -->
<div class="input-group">
  <div class="input-addon-start">$</div>
  <input type="text" class="input" placeholder="Amount">
  <div class="input-addon-end">.00</div>
</div>

<!-- Input with icons -->
<div class="input-group">
  <div class="input-icon-start">
    <i class="fa-solid fa-search"></i>
  </div>
  <input type="text" class="input" placeholder="Search...">
</div>

<!-- Textarea variants -->
<textarea class="textarea" placeholder="Default"></textarea>
<textarea class="textarea input-sm" placeholder="Small"></textarea>
<textarea class="textarea input-lg" placeholder="Large"></textarea>

<!-- Select input -->
<select class="input">
  <option>Select an option...</option>
</select>
```

### Badges

```html
<span class="badge badge-default">Default</span>
<span class="badge badge-secondary">Secondary</span>
<span class="badge badge-destructive">Error</span>
<span class="badge badge-success">Success</span>
<span class="badge badge-warning">Warning</span>
<span class="badge badge-info">Info</span>
<span class="badge badge-outline">Outline</span>

<!-- Sizes -->
<span class="badge badge-default badge-sm">Small</span>
<span class="badge badge-default badge-lg">Large</span>
```

### Alerts

```html
<div class="alert alert-default">
  <div class="alert-icon">ℹ️</div>
  <div class="alert-content">
    <div class="alert-title">Information</div>
    <div class="alert-description">This is an informational message</div>
  </div>
</div>

<!-- Alert variants -->
<div class="alert alert-success">...</div>
<div class="alert alert-warning">...</div>
<div class="alert alert-destructive">...</div>
<div class="alert alert-info">...</div>
```

### Navigation

For navigation bars, tabs, and filters, use the `.btn-subtle` variant with the `.active` class:

```html
<!-- Navigation bar -->
<nav class="row gap-2">
  <a href="/" class="btn btn-subtle active">Home</a>
  <a href="/about" class="btn btn-subtle">About</a>
  <a href="/contact" class="btn btn-subtle">Contact</a>
</nav>

<!-- Tabs -->
<div class="row gap-2">
  <button class="btn btn-subtle active">Overview</button>
  <button class="btn btn-subtle">Analytics</button>
  <button class="btn btn-subtle">Reports</button>
</div>
```

The subtle variant provides a clean, professional look with:
- Transparent background by default
- Muted background on hover
- Primary (brand color) background when active
- Perfect for navigation elements that shouldn't dominate the UI

### Table of Contents

Dynamic sidebar navigation that automatically generates from page headings with active state tracking.

```html
<!-- Place where TOC should appear -->
<div data-toc></div>

<!-- Add IDs to your headings -->
<h2 id="section-1">Main Section</h2>
<h3 id="subsection-1-1">Subsection</h3>
<h2 id="section-2">Another Section</h2>
```

**Features:**
- Auto-generates from `h2[id]` and `h3[id]` headings
- Sticky sidebar positioning (desktop only, hidden on mobile <1024px)
- Active state tracking with IntersectionObserver
- Smooth scrolling with header offset
- Nested h3 headings appear indented
- "On this page" title automatically added
- Updates URL hash for shareable section links

**Typical Layout:**
```html
<div class="container-xl">
  <div class="row" style="gap: var(--spacing-8);">
    <!-- Main content -->
    <div style="flex: 1; min-width: 0;">
      <h1>Page Title</h1>
      <h2 id="section-1">Section 1</h2>
      <p>Content...</p>
    </div>
    
    <!-- TOC sidebar -->
    <aside style="width: 240px; flex-shrink: 0;">
      <div data-toc></div>
    </aside>
  </div>
</div>
```

### Dropdowns & Submenus

CSS-only hover-triggered dropdown menus, perfect for navigation bars.

```html
<!-- Basic dropdown -->
<div class="dropdown">
  <button class="btn btn-default dropdown-trigger">
    Options
  </button>
  <div class="dropdown-content">
    <a href="#" class="dropdown-item">
      <i class="fa-solid fa-user"></i>
      Profile
    </a>
    <a href="#" class="dropdown-item">
      <i class="fa-solid fa-cog"></i>
      Settings
    </a>
    <div class="dropdown-separator"></div>
    <a href="#" class="dropdown-item">
      <i class="fa-solid fa-sign-out"></i>
      Logout
    </a>
  </div>
</div>

<!-- With labels and shortcuts -->
<div class="dropdown">
  <button class="btn btn-outline dropdown-trigger">
    File Menu
  </button>
  <div class="dropdown-content">
    <div class="dropdown-label">Document</div>
    <a href="#" class="dropdown-item">
      <i class="fa-solid fa-file"></i>
      New File
      <span class="dropdown-shortcut">⌘N</span>
    </a>
    <a href="#" class="dropdown-item">
      <i class="fa-solid fa-save"></i>
      Save
      <span class="dropdown-shortcut">⌘S</span>
    </a>
    <div class="dropdown-separator"></div>
    <div class="dropdown-label">Danger Zone</div>
    <a href="#" class="dropdown-item dropdown-item-destructive">
      <i class="fa-solid fa-trash"></i>
      Delete
    </a>
  </div>
</div>

<!-- Navigation bar integration -->
<nav>
  <a href="#">Home</a>
  
  <div class="dropdown">
    <a href="#" class="dropdown-trigger">Products</a>
    <div class="dropdown-content">
      <a href="#" class="dropdown-item">
        <i class="fa-solid fa-box"></i>
        All Products
      </a>
      <a href="#" class="dropdown-item">
        <i class="fa-solid fa-star"></i>
        Featured
      </a>
    </div>
  </div>
</nav>

<!-- Alignment variants -->
<div class="dropdown dropdown-right">Right-aligned dropdown</div>
<div class="dropdown dropdown-center">Center-aligned dropdown</div>

<!-- Optional animations -->
<div class="dropdown dropdown-animated">
  <button class="btn btn-default dropdown-trigger">
    With Animation
  </button>
  <div class="dropdown-content">
    <a href="#" class="dropdown-item">Option 1</a>
    <a href="#" class="dropdown-item">Option 2</a>
  </div>
</div>

<!-- User menu (right-aligned) -->
<div class="dropdown dropdown-right">
  <button class="btn btn-ghost dropdown-trigger">
    <i class="fa-solid fa-user-circle"></i>
    John Doe
  </button>
  <div class="dropdown-content">
    <div class="dropdown-label">Account</div>
    <a href="#" class="dropdown-item">Profile</a>
    <a href="#" class="dropdown-item">Settings</a>
    <div class="dropdown-separator"></div>
    <a href="#" class="dropdown-item dropdown-item-destructive">Logout</a>
  </div>
</div>
```

**Features:**
- ✅ **CSS-Only**: No JavaScript required, pure hover states
- ✅ **Auto Chevron**: Triggers automatically get rotating chevron icon
- ✅ **Optional Animations**: Add `.dropdown-animated` for smooth fade/slide transitions (instant by default)
- ✅ **Keyboard Accessible**: Works with `:focus-within`
- ✅ **Mobile Friendly**: Converts to focus-based on mobile
- ✅ **Dark Mode**: Enhanced shadows in dark mode

## 🏗️ Layout Atoms

### Flexbox Layouts

```html
<!-- Row (horizontal) -->
<div class="row">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

<!-- Column (vertical) -->
<div class="col">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

<!-- Alignment utilities -->
<div class="row center">Centered both axes</div>
<div class="row center-x">Centered horizontally</div>
<div class="row center-y">Centered vertically</div>
<div class="row between">Space between items</div>
<div class="row start">Align to start</div>
<div class="row end">Align to end</div>

<!-- Responsive -->
<div class="row xs-col">Row on desktop, column on XS screens</div>
<div class="row md-col">Row on desktop, column on tablets/mobile</div>
```

### Grid Layouts

```html
<!-- Fixed columns -->
<div class="grid grid-cols-3">
  <div>Column 1</div>
  <div>Column 2</div>
  <div>Column 3</div>
</div>

<!-- Responsive auto-fit -->
<div class="grid-auto-fit">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

<!-- Column spanning -->
<div class="grid grid-cols-4">
  <div class="col-span-2">Spans 2 columns</div>
  <div>Normal</div>
  <div>Normal</div>
</div>
```

## � Gradients & Visual Utilities

Gradient helper classes for marketing surfaces:

```html
<div class="gradient-primary-accent rounded p-6 text-white">Primary → Accent</div>
<div class="gradient-green rounded p-6 text-white">Green</div>
<div class="gradient-purple rounded p-6 text-white">Purple</div>
<div class="gradient-amber rounded p-6 text-white">Amber</div>
<div class="gradient-blue rounded p-6 text-white">Blue</div>
<div class="gradient-pink rounded p-6 text-white">Pink</div>
```

Subtle blends: `gradient-muted-card` for placeholders (video, skeleton areas).

### Extended Shadows

| Class          | Token            | Usage                                       |
| -------------- | ---------------- | -------------------------------------------- |
| `shadow-soft`  | `--shadow-soft`  | Light elevation for avatars, icon blocks     |
| `shadow-float` | `--shadow-float` | Interactive hover elements                   |
| `shadow-focus` | `--shadow-focus` | Prominent focal action (e.g., play button)   |
| `shadow-hero`  | `--shadow-hero`  | Large hero gradient cards / CTAs             |

### Translucent Surfaces

```html
<header class="sticky top-0 z-50 bg-surface-translucent backdrop-blur border-b">
  ...
</header>
```
Use `bg-muted-subtle` to softly tint entire sections: `<section class="py-12 bg-muted-subtle">`.

## 📐 Directional Spacing

Directional utilities complement the base `.p-*` & `.m-*` classes:

| Axis                | Examples                                 |
| ------------------- | ----------------------------------------- |
| Padding X / Y       | `.px-4`, `.py-12`                         |
| Padding single side | `.pt-8`, `.pb-6`, `.pl-4`, `.pr-2`        |
| Margin X / Y        | `.mx-auto`, `.my-4`                       |
| Margin single side  | `.mt-8`, `.mb-12`, `.ml-4`, `.mr-2`       |
| Overlap             | `.-ml-3` (avatar stacking)                |

Scale values: 0,1,2,3,4,6,8,10,12,16 (consistent with spacing tokens).

## 🧩 Marketing Patterns

Purpose-built classes for landing page sections.

### Feature Rows
```html
<div class="feature-row">
  <div class="col gap-3" style="flex:1;">
    <div class="feature-icon gradient-primary-accent"><i class="fa-solid fa-calendar"></i></div>
    <h3 class="text-xl font-semibold">Smart Scheduling</h3>
  </div>
  <div class="col" style="flex:2;">
    <p class="text-lg text-muted">Queue posts weeks in advance…</p>
  </div>
</div>
<div class="feature-row feature-row-reverse"> ... </div>
```

### Avatar Stack
```html
<div class="avatar-stack">
  <span class="avatar gradient-indigo">K</span>
  <span class="avatar gradient-fuchsia -ml-3">L</span>
  <span class="avatar gradient-cyan -ml-3">D</span>
</div>
```

### Hero Gradient Card
```html
<div class="card card-hero p-12 col center gap-6">
  <h2 class="text-3xl font-bold text-center">Ready to transform?</h2>
  <button class="btn btn-lg btn-invert shadow-float">Get Started</button>
</div>
```

### Icon Tile
```html
<div class="icon-tile icon-tile-sm"><i class="fa-solid fa-bridge"></i></div>
```

### Guidance

- Use utilities for bespoke layouts.
- Use patterns for repeatable marketing sections.
- Combine gradients & shadows for emphasis: `<div class="feature-icon gradient-blue shadow-soft">`.

## 🔄 Migration (If Upgrading)

1. Replace inline gradient backgrounds with `.gradient-*` classes.
2. Swap custom box-shadow values for `shadow-*` utilities.
3. Convert avatar overlaps into `.avatar-stack` with `-ml-3`.
4. Replace hero CTA blocks with `.card-hero`.
5. Use directional spacing utilities instead of manual padding/margins.

## �🎨 Design Tokens

### Color System

```html
<!-- Background colors -->
<div class="bg-background">Background</div>
<div class="bg-card">Card background</div>
<div class="bg-primary">Primary</div>
<div class="bg-secondary">Secondary</div>
<div class="bg-muted">Muted</div>
<div class="bg-accent">Accent</div>

<!-- Text colors -->
<p class="text-foreground">Foreground</p>
<p class="text-muted">Muted text</p>
<p class="text-primary">Primary</p>
<p class="text-destructive">Destructive</p>
<p class="text-success">Success</p>

```

### 🎯 Customizing Colors

All colors are defined as CSS variables in HSL format, making them **easy to customize**. Simply override them in your project's CSS file after importing bare-v2:

```css
/* In your project's CSS file (after importing bare-v2) */
:root {
  /* 🎨 Customize accent color to match your brand */
  --accent: 280 90% 65%;                /* Purple accent */
  --accent-foreground: 210 40% 98%;     /* Text color on accent background */
  
  /* Override other semantic colors as needed */
  --primary: 200 80% 50%;               /* Your brand color */
  --secondary: 220 70% 45%;             /* Secondary brand color */
  --success: 150 80% 40%;               /* Success green */
  --warning: 40 100% 50%;               /* Warning amber */
  --destructive: 0 85% 60%;             /* Error red */
}

/* Dark mode versions - typically lighter/more vibrant */
.dark,
[data-theme="dark"] {
  --accent: 280 90% 75%;                /* Lighter purple for dark mode */
  --accent-foreground: 222.2 84% 4.9%;  /* Dark text on light accent */
  
  --primary: 200 80% 60%;               /* Adjust other colors similarly */
}
```

**HSL Format**: `hue saturation% lightness%`
- **Hue**: 0-360 (0=red, 120=green, 240=blue, 280=purple, 180=cyan)
- **Saturation**: 0-100% (0=gray, 100=vivid)
- **Lightness**: 0-100% (0=black, 50=pure color, 100=white)

**Pro tip**: For dark mode, increase lightness by 10-15% to maintain vibrancy against dark backgrounds.

### Quick Accent Color Examples

```css
/* Vibrant Blue (default) */
:root {
  --accent: 217 91% 60%;
}
.dark { --accent: 217 91% 70%; }

/* Purple */
:root {
  --accent: 280 90% 65%;
}
.dark { --accent: 280 90% 75%; }

/* Teal */
:root {
  --accent: 180 85% 50%;
}
.dark { --accent: 180 85% 60%; }

/* Magenta */
:root {
  --accent: 320 90% 60%;
}
.dark { --accent: 320 90% 70%; }

/* Orange */
:root {
  --accent: 30 95% 55%;
}
.dark { --accent: 30 95% 65%; }
```

### Spacing

```html
<!-- Gap utilities (for flex/grid) -->
<div class="row gap-1">Tiny gap (4px)</div>
<div class="row gap-2">Small gap (8px)</div>
<div class="row gap-4">Medium gap (16px)</div>
<div class="row gap-6">Large gap (24px)</div>

<!-- Padding -->
<div class="p-4">Padding all sides</div>

<!-- Margin -->
<div class="m-4">Margin all sides</div>
<div class="mx-auto">Center horizontally</div>
```

### Typography

```html
<!-- Sizes -->
<p class="text-xs">Extra small (12px)</p>
<p class="text-sm">Small (14px)</p>
<p class="text-base">Base (16px)</p>
<p class="text-lg">Large (18px)</p>
<p class="text-xl">Extra large (20px)</p>
<p class="text-2xl">2XL (24px)</p>

<!-- Weights -->
<p class="font-light">Light (300)</p>
<p class="font-normal">Normal (400)</p>
<p class="font-medium">Medium (500)</p>
<p class="font-semibold">Semibold (600)</p>
<p class="font-bold">Bold (700)</p>
```

### Shadows & Borders

```html
<!-- Shadows -->
<div class="shadow-sm">Small shadow</div>
<div class="shadow-md">Medium shadow</div>
<div class="shadow-lg">Large shadow</div>

<!-- Border radius -->
<div class="rounded-sm">Small radius (2px)</div>
<div class="rounded-md">Medium radius (6px)</div>
<div class="rounded-lg">Large radius (8px)</div>
<div class="rounded-full">Fully rounded</div>

<!-- Borders -->
<div class="border">All borders</div>
<div class="border-t">Top border only</div>
<div class="border-default">With default color</div>
```

## 🔧 Advanced Utilities

### Overlay & Glass Effects

```html
<!-- Full-screen overlay with backdrop blur -->
<div class="overlay">
  <div class="card">Modal content</div>
</div>

<!-- Glassmorphism effect -->
<div class="glass">
  <p>Frosted glass appearance with backdrop blur</p>
</div>
```

### Tooltips

```html
<!-- Simple tooltip on hover -->
<span class="tooltip" data-tooltip="Helpful information">
  Hover over me
</span>
```

### Dividers

```html
<!-- Horizontal divider -->
<p>Content above</p>
<div class="divider"></div>
<p>Content below</p>

<!-- Vertical divider -->
<div class="row">
  <span>Left</span>
  <div class="divider-vertical"></div>
  <span>Right</span>
</div>
```

### Scroll Utilities

```html
<!-- Enable scrolling on both axes -->
<div class="scroll" style="max-height: 200px;">
  Long content...
</div>

<!-- Horizontal scroll only -->
<div class="scroll-x">
  Wide content...
</div>

<!-- Vertical scroll only -->
<div class="scroll-y" style="max-height: 200px;">
  Tall content...
</div>
```

### Text Truncation

```html
<!-- Single line truncation -->
<p class="truncate" style="max-width: 200px;">
  This text will be truncated with an ellipsis...
</p>

<!-- Multi-line clamping (2-6 lines) -->
<p class="text-clamp-2" style="max-width: 300px;">
  This text will be clamped to two lines with an ellipsis at the end.
  Any additional content beyond two lines will be hidden.
</p>

<!-- Available: .text-clamp-1 through .text-clamp-6 -->
```

### Additional Utilities

```html
<!-- Center block element -->
<div class="centered" style="width: 200px;">Centered</div>

<!-- Display: contents (children behave as direct siblings) -->
<div class="row">
  <div class="contents">
    <span>A</span>
    <span>B</span>
  </div>
  <span>C</span>
</div>

<!-- Visibility utilities -->
<div class="hidden">Hidden with display: none</div>
<div class="invisible">Hidden but takes up space</div>
<div class="vanish">Completely hidden (!important)</div>
```

## 🌗 Dark Mode

```html
<!-- Toggle dark mode with JavaScript -->
<button onclick="document.documentElement.classList.toggle('dark')">
  Toggle Dark Mode
</button>

<!-- Or use data-theme attribute -->
<button onclick="document.documentElement.setAttribute('data-theme', 'dark')">
  Enable Dark Mode
</button>
```

All components automatically adapt to dark mode when `.dark` class or `data-theme="dark"` is applied to the HTML element.

## 📐 Layout Patterns

bare-v2 includes composable layout patterns for common UI structures. All patterns use semantic BEM-style modifiers and are fully responsive.

### Page Structure

```html
<!-- Standard page layout (min-height: 100vh, natural flow) -->
<div class="page">
  <header class="page-header">
    <div class="container-xl">
      <!-- Header content -->
    </div>
  </header>

  <main class="page-main">
    <div class="container-xl">
      <!-- Main content -->
    </div>
  </main>

  <footer class="page-footer">
    <div class="container-xl">
      <!-- Footer content -->
    </div>
  </footer>
</div>
```

### Centered Layouts

```html
<!-- Center content both horizontally and vertically -->
<div class="layout layout--centered layout--fullscreen">
  <div class="card">
    <div class="card-header">
      <h3 class="card-title">Login</h3>
    </div>
    <div class="card-content">
      <!-- Login form -->
    </div>
  </div>
</div>

<!-- Centered with width constraint (max 768px) -->
<div class="narrow">
  <div class="card">
    <!-- Constrained content -->
  </div>
</div>
```

### Fixed Header Layout

```html
<!-- Header stays fixed at top while content scrolls -->
<div class="layout layout--fixed-header layout--fullscreen">
  <header class="layout-header">
    <nav class="row between-x center-y">
      <h1>App Name</h1>
      <button class="btn btn-primary">Action</button>
    </nav>
  </header>
  
  <main class="layout-main">
    <!-- Scrollable content with automatic margin-top -->
  </main>
</div>
```

### Sidebar Layouts

Professional sidebar navigation with full responsive support and toggle functionality.

```html
<!-- Professional sidebar on the left (250px fixed width) -->
<div class="layout layout--sidebar-left layout--fullscreen">
  <aside class="layout-sidebar">
    <div style="margin-bottom: var(--spacing-6);">
      <h3 class="font-bold text-lg">My App</h3>
      <p class="text-xs text-muted">Dashboard</p>
    </div>
    
    <nav class="sidebar-nav">
      <button class="btn btn-default btn-sm">
        <i class="fa-solid fa-home"></i>
        <span>Dashboard</span>
      </button>
      <button class="btn btn-ghost btn-sm">
        <i class="fa-solid fa-users"></i>
        <span>Users</span>
      </button>
      <button class="btn btn-ghost btn-sm">
        <i class="fa-solid fa-cog"></i>
        <span>Settings</span>
      </button>
    </nav>
  </aside>
  
  <main class="layout-main">
    <!-- Main content takes remaining space -->
  </main>
</div>

<!-- Sidebar on the right -->
<div class="layout layout--sidebar-right layout--fullscreen">
  <aside class="layout-sidebar">
    <!-- Side panel content (filters, metadata, etc.) -->
  </aside>
  
  <main class="layout-main">
    <!-- Main content -->
  </main>
</div>

<!-- Collapsible sidebar (icon-only mode) -->
<div class="layout layout--sidebar-left layout--sidebar-collapsed">
  <aside class="layout-sidebar">
    <!-- Sidebar collapses to 60px, showing only icons -->
    <nav class="sidebar-nav">
      <button class="btn btn-default btn-sm" title="Dashboard">
        <i class="fa-solid fa-home"></i>
        <span>Dashboard</span> <!-- Hidden when collapsed -->
      </button>
    </nav>
  </aside>
  <main class="layout-main">...</main>
</div>

<!-- Toggle collapsed state with JavaScript -->
<script>
  function toggleSidebar() {
    document.querySelector('.layout').classList.toggle('layout--sidebar-collapsed');
  }
</script>
```

**Responsive Sidebar Options:**

```html
<!-- Option 1: Stack vertically on mobile (<768px) -->
<div class="layout layout--sidebar-left layout--stack">
  <!-- Sidebar stacks above content on small screens -->
  <!-- Good for content-heavy sidebars -->
</div>

<!-- Option 2: Hide sidebar on mobile -->
<div class="layout layout--sidebar-left layout--hide-sidebar">
  <!-- Sidebar completely hidden on small screens -->
  <!-- Use with hamburger menu to show/hide programmatically -->
</div>

<!-- Option 3: Overlay mode on mobile (recommended) -->
<div class="layout layout--sidebar-left layout--sidebar-mobile">
  <aside class="layout-sidebar">
    <!-- Fixed overlay on mobile, slides in from left -->
    <!-- Add .sidebar-open class to show -->
  </aside>
  <main class="layout-main">...</main>
</div>

<!-- Toggle mobile overlay with JavaScript -->
<button onclick="document.querySelector('.layout').classList.toggle('sidebar-open')">
  <i class="fa-solid fa-bars"></i> Menu
</button>
```

**Professional Sidebar Navigation:**

The `.sidebar-nav` class provides consistent styling for navigation buttons:

```html
<nav class="sidebar-nav">
  <!-- Active state -->
  <button class="btn btn-default btn-sm">
    <i class="fa-solid fa-home"></i>
    <span>Dashboard</span>
  </button>
  
  <!-- Default state -->
  <button class="btn btn-ghost btn-sm">
    <i class="fa-solid fa-users"></i>
    <span>Users</span>
  </button>
  
  <!-- With divider -->
  <div class="divider" style="margin: var(--spacing-4) 0;"></div>
  
  <button class="btn btn-ghost btn-sm">
    <i class="fa-solid fa-cog"></i>
    <span>Settings</span>
  </button>
</nav>
```

**Sidebar Features:**
- 250px default width, 60px collapsed
- Smooth transitions between states
- Professional button styling with icons
- Automatic overflow scrolling
- Mobile-friendly overlay mode
- Full dark mode support

### Fullscreen Layout

```html
<!-- Full viewport height with header, scrollable content, and footer -->
<div class="layout layout--fullscreen">
  <header class="layout-header">
    <!-- Fixed-height header -->
  </header>
  
  <main class="layout-main">
    <!-- Fills remaining space, scrollable if needed -->
  </main>
  
  <footer class="layout-footer">
    <!-- Fixed-height footer -->
  </footer>
</div>
```

### Combining Patterns

```html
<!-- Fixed header + sidebar + fullscreen -->
<div class="layout layout--fixed-header layout--sidebar-left layout--fullscreen">
  <header class="layout-header">
    <!-- Fixed navigation -->
  </header>
  
  <aside class="layout-sidebar">
    <!-- Side navigation -->
  </aside>
  
  <main class="layout-main">
    <!-- Main app content -->
  </main>
</div>
```

### Containers

```html
<!-- Responsive containers with max-width -->
<div class="container-sm">Max 640px</div>
<div class="container-md">Max 768px</div>
<div class="container-lg">Max 1024px</div>
<div class="container-xl">Max 1280px</div>
<div class="container-2xl">Max 1536px</div>

<!-- Use inside layout-main for constrained content -->
<main class="layout-main">
  <div class="container-lg">
    <!-- Content limited to 1024px width, centered -->
  </div>
</main>
```

### Section Layouts

```html
<!-- Flexible column container with gap -->
<section class="section">
  <h2>Section Title</h2>
  <p>Content with automatic vertical spacing</p>
</section>

<!-- Section variants -->
<section class="section section-card">With card styling</section>
<section class="section section-elevated">With elevated shadow</section>
<section class="section section-bordered">With border</section>
<section class="section section-muted">With muted background</section>

<!-- Section modifiers -->
<section class="section section-compact">Less padding</section>
<section class="section section-spacious">More padding</section>
<section class="section section-narrow">Max-width 768px, centered</section>
<section class="section section-horizontal">Row direction</section>
```

### Pattern Decision Guide

**Choose the right pattern:**

- **Centered content** (login, 404, landing) → `.layout.layout--centered`
- **Fixed navigation** → `.layout.layout--fixed-header`
- **App with sidebar** → `.layout.layout--sidebar-left` or `.layout--sidebar-right`
- **Full-screen app** → `.layout.layout--fullscreen`
- **Content page** → `.page` with `.page-header`, `.page-main`, `.page-footer`
- **Constrained content** → `.narrow` or `.container-{size}`

**Sidebar options:**
- **Standard sidebar** → `.layout--sidebar-left` (250px wide)
- **Collapsible sidebar** → Add `.layout--sidebar-collapsed` (60px icon-only mode)
- **Mobile overlay** → Add `.layout--sidebar-mobile` (slides in on mobile)
- **Stack on mobile** → Add `.layout--stack` (sidebar above/below content)
- **Hide on mobile** → Add `.layout--hide-sidebar` (completely hidden)

**Responsive behavior:**
- Mobile breakpoint: **768px**
- Collapsible: **Toggle with JavaScript** (`.classList.toggle()`)
- Professional nav: Use `.sidebar-nav` for consistent button styling

## 🎓 LLM Usage Guide

When prompting an LLM to generate UI with bare-v2, use these patterns:

### Effective Prompts

```
✅ "Create a card with an elevated shadow effect"
→ <div class="card card-elevated">

✅ "Add a destructive button for deletion"
→ <button class="btn btn-destructive">Delete</button>

✅ "Layout 3 items horizontally with space between"
→ <div class="row between">

✅ "Show an error alert with icon"
→ <div class="alert alert-destructive">
```

### Naming Conventions

- **Components**: `{component}-{variant}` (e.g., `btn-outline`, `card-elevated`)
- **Layout**: Descriptive atoms (e.g., `row`, `col`, `center`, `between`)
- **States**: Semantic names (e.g., `btn-loading`, `input-error`)
- **Sizes**: Standard scale (e.g., `btn-sm`, `btn-lg`, `badge-lg`)

## 🛠️ Building from Source

```bash
# Clone and install
git clone https://github.com/livz/bare-v2
cd bare-v2
bun install

# Build everything (CSS + HTML)
bun run build

# Build only CSS
bun run build:css

# Build only HTML demos
bun run build:html

# View demo (builds and opens)
bun run demo

# Development with watch mode (watches both CSS and HTML)
bun run dev

# Watch only CSS
bun run dev:css

# Watch only HTML templates
bun run dev:html

# Build, open demo, and watch for changes
bun run demo:watch
```

### Demo Development

The demo pages use an EJS templating system. Generated files are in `build/demo/` (not committed):

```bash
# Directory structure
demo/templates/          # Source templates (edit these!)
├── layout.ejs           # Main layout wrapper
├── partials/            # Reusable components
│   ├── head.ejs        # HTML head, meta tags, styles
│   ├── nav.ejs         # Navigation bar
│   ├── scripts.ejs     # Common JavaScript
│   └── styles.ejs      # Demo-specific styles
└── pages/              # Page content (no boilerplate)
    ├── index.ejs
    ├── components.ejs
    └── ...

build/demo/             # Generated HTML (gitignored)
├── index.html          # Don't edit these!
├── components.html
└── ...

# Development workflow
bun run demo:watch      # Build, open, and watch for changes

# Or manually
vim demo/templates/pages/index.ejs
bun run build:html
open build/demo/index.html
```

See `demo/templates/README.md` for detailed documentation on the templating system.

## 📦 Package Exports

```javascript
// Import full CSS
import '@livx.cc/bare-v2/dist/bare.css'

// Import JavaScript API (optional)
import '@livx.cc/bare-v2/scripts'
// or 
import bare from '@livx.cc/bare-v2/scripts'

// Import LESS modules
import '@livx.cc/bare-v2/less/tokens'
import '@livx.cc/bare-v2/less/primitives'
```

## 🚀 JavaScript API

bare-v2 includes a minimal, optional JavaScript API for functionality that cannot be achieved with CSS alone:

```html
<script src="https://cdn.jsdelivr.net/npm/@livx.cc/bare-v2/dist/bare.min.js"></script>
<script>
  // Toast notifications (requires JS for timing & stacking)
  bare.toast.success('Success!', 'Operation completed');
  bare.toast.error('Error!', 'Something went wrong');
  
  // Theme management (requires JS for localStorage & system detection)
  bare.theme.toggle(); // Switch between light/dark
  bare.theme.set('dark'); // Set specific theme
</script>
```

**Philosophy: Minimal JavaScript**
- Only includes functionality that **cannot** be achieved with pure CSS
- Toasts: Require timing, auto-dismiss, and dynamic stacking
- Theme: Requires localStorage persistence and system preference detection
- Everything else (loaders, animations, states) is handled by CSS classes

Features:
- **Lightweight**: ~5KB minified (only essential functionality)
- **Type-safe**: Full TypeScript support
- **Framework-agnostic**: Works with any setup

<!-- (Philosophy section consolidated near top; legacy subsection removed to avoid duplication) -->

## 🛠 Contributing

Before opening a PR, read the [Repository Guidelines](AGENTS.md) for structure, workflow, and review expectations tailored to this project.

## ✍️ Authoring Guidelines

Concise, actionable rules (Philosophy above covers the why):

### Layer Usage
Atoms (layout primitives) → Primitives (semantic components) → Patterns (compositions) → Utilities (single-purpose helpers). Tokens stay internal.

### Decide: Atom or Utility?
Ask: "Will this be stacked with others to shape layout?" → Atom.  "Does it do exactly one visual/behavioral tweak?" → Utility (prefix `bare-`).

### Naming
- Intent over implementation (`card-elevated`, not `shadow-lg`).
- Utilities must start with `bare-`.
- Pattern modifiers: `block--variant` (alias legacy `block-variant` during transition).

### Composition Rules
- Stack only atoms together for layout scaffolding.
- Primitives never hard-code raw values—depend on tokens via existing variables.
- Patterns compose primitives/atoms; no re-implementing token math.
- Utilities do one thing; avoid chaining multiple utilities where a primitive or pattern fits.

### DO / AVOID
DO: `<div class="flex gap center"><div class="card card-elevated">...</div></div>`
AVOID: Recreating a button with utilities instead of using `.btn`.
AVOID: Embedding raw color hex in patterns.

### Contribution Checklist
- Layer respected (atoms → primitives → patterns → utilities).
- New utility prefixed `bare-`.
- No duplicate class semantics introduced.
- Dark mode styles included (use existing variables).
- Demo updated if new public surface added.
- Authoring rationale (1–2 lines) added if non-obvious.

## 📄 Licenses

MIT © livz

## 🔗 Links

- [GitHub Repository](https://github.com/livz/bare-v2)
- [NPM Package](https://npmjs.com/package/@livx.cc/bare-v2)
- [Demo Site](https://livshitz.github.io/bare-v2/) - Live examples and documentation

---

**Built with ❤️ for humans and AI**