@livx.cc/bare-v2

v2.2.2

Published

2 months ago

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

0High
0Medium
0Low

elya_livshitz

css less design-system shadcn tailwind llm-friendly semantic-css ui-components

@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:

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

<!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

# 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

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

Modular LESS Imports

// 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

<!-- 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:

<!-- 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

<!-- 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

<!-- Basic input with label -->
<div class="form-group">
  <label class="label">Email Address</label>
  <input type="email" class="input" placeholder="[email protected]">
  <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

<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

<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:

<!-- 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

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

<!-- 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:

<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.

<!-- 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

<!-- 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

<!-- 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:

<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

<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

<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

<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

<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

<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)

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

�🎨 Design Tokens

Color System

<!-- 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:

/* 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

/* 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

<!-- 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

<!-- 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

<!-- 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

<!-- 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

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

Dividers

<!-- 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

<!-- 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

<!-- 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

<!-- 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

<!-- 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

<!-- 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

<!-- 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

<!-- 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.

<!-- 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:

<!-- 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:

<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

<!-- 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

<!-- 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

<!-- 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

<!-- 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

# 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):

# 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

// 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:

<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

🛠 Contributing

Before opening a PR, read the Repository Guidelines 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
NPM Package
Demo Site - Live examples and documentation

Built with ❤️ for humans and AI

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@livx.cc/bare-v2

Philosophy

✨ Key Features

🚀 Quick Start

CDN Usage (Fastest)

NPM Installation

Import Full CSS

Modular LESS Imports

🎯 Core Components

Buttons

Cards

Form Controls

Badges

Alerts

Navigation

Table of Contents

Dropdowns & Submenus

🏗️ Layout Atoms

Flexbox Layouts

Grid Layouts

� Gradients & Visual Utilities

Extended Shadows

Translucent Surfaces

📐 Directional Spacing

🧩 Marketing Patterns

Feature Rows

Avatar Stack

Hero Gradient Card

Icon Tile

Guidance

🔄 Migration (If Upgrading)

�🎨 Design Tokens

Color System

🎯 Customizing Colors

Quick Accent Color Examples

Spacing

Typography

Shadows & Borders

🔧 Advanced Utilities

Overlay & Glass Effects

Tooltips

Dividers

Scroll Utilities

Text Truncation

Additional Utilities

🌗 Dark Mode

📐 Layout Patterns

Page Structure

Centered Layouts

Fixed Header Layout

Sidebar Layouts

Fullscreen Layout

Combining Patterns

Containers

Section Layouts

Pattern Decision Guide

🎓 LLM Usage Guide

Effective Prompts

Naming Conventions

🛠️ Building from Source

Demo Development

📦 Package Exports

🚀 JavaScript API

🛠 Contributing

✍️ Authoring Guidelines

Layer Usage

Decide: Atom or Utility?

Naming

Composition Rules

DO / AVOID

Contribution Checklist

📄 Licenses

🔗 Links