Package Exports

littlebrand-ui-kit
littlebrand-ui-kit/dist/littlebrand-ui.css
littlebrand-ui-kit/style.css

Readme

LittleBrand UI Kit

A modern Vue 3 UI component library with a powerful color generation system. Build beautiful, accessible interfaces with minimal effort.

✨ Features

🎨 Radix UI Color System - Professional color scales with precise OKLCH values
🚀 Runtime Theming - Change colors instantly without rebuilding
📦 20+ Components - Buttons, forms, dialogs, navigation, and more
🌙 Dark Mode - Opt-in dark mode with optimized colors
🎯 Zero Config - Works out of the box with beautiful defaults
🌳 Tree-Shakeable - Only bundle what you use
💅 SASS + Pug - Clean, maintainable component code
📝 312 CSS Variables - Complete control over typography, spacing, and colors
🔤 Flexible Typography - Three independent font families for headings, body, and UI elements
🎭 Alpha Scales - Complete transparency scales for overlays and subtle backgrounds
🤖 MCP Server Integration - Built-in AI assistant tools for accurate component and token discovery

📦 Installation

npm install littlebrand-ui-kit

🚀 Quick Start

Method 1: Global Plugin Installation (All Components)

import { createApp } from 'vue'
import App from './App.vue'
import { LittleBrandUI, applyTheme } from 'littlebrand-ui-kit'
import 'littlebrand-ui-kit/style.css'

// OPTIONAL: Customize colors (one hex = entire color system!)
applyTheme({
  primary: '#AB4ABA',    // Your brand purple
  secondary: '#F76B15'   // Your brand orange
  // Generates all shades, dark mode, and semantic tokens automatically!
})

const app = createApp(App)
app.use(LittleBrandUI)  // Registers all components globally
app.mount('#app')

Method 2: Import as Needed (Recommended - Tree-shaking)

Import only the components you need in each file:

// main.js - Setup and theme customization
import { createApp } from 'vue'
import App from './App.vue'
import { applyTheme } from 'littlebrand-ui-kit'
import 'littlebrand-ui-kit/style.css'

// OPTIONAL: Customize colors globally
applyTheme({
  primary: '#8b5cf6',
  secondary: '#f59e0b'
})

const app = createApp(App)
app.mount('#app')

<!-- Any component file -->
<script setup>
import { LbButton, LbInput } from 'littlebrand-ui-kit'
</script>

<template>
  <lb-button variant="filled" color="primary">
    Click Me
  </lb-button>
  <lb-input v-model="text" placeholder="Enter text" />
</template>

Method 3: Manual Global Registration

import { createApp } from 'vue'
import App from './App.vue'
import { 
  LbButton, 
  LbInput, 
  LbDialog,
  applyTheme 
} from 'littlebrand-ui-kit'
import 'littlebrand-ui-kit/style.css'

// Customize colors
applyTheme({
  primary: '#AB4ABA',
  secondary: '#F76B15',
  neutral: '#94a3b8',
  success: '#10b981',
  warning: '#f59e0b',
  error: '#ef4444'
})

// Make applyTheme available globally for runtime theme changes
window.applyTheme = applyTheme

const app = createApp(App)

// Register only the components you need globally
app.component('LbButton', LbButton)
app.component('LbInput', LbInput)
app.component('LbDialog', LbDialog)

app.mount('#app')

With SnackbarProvider

To use snackbars, wrap your app with LbSnackbarProvider:

import { createApp, h } from 'vue'
import App from './App.vue'
import { LbSnackbarProvider, applyTheme } from 'littlebrand-ui-kit'
import 'littlebrand-ui-kit/style.css'

// Customize colors
applyTheme({ primary: '#8b5cf6' })

const app = createApp({
  render() {
    return h(LbSnackbarProvider, () => h(App))
  }
})
app.mount('#app')

Then use snackbars anywhere:

<script setup>
import { useSnackbar } from 'littlebrand-ui-kit'

const { showSnackbar } = useSnackbar()

const handleClick = () => {
  showSnackbar({ 
    message: 'Action completed!',
    variant: 'success'
  })
}
</script>

🎨 Color Customization

Method 1: Runtime JavaScript (Easiest)

Change colors instantly without any build step:

import { applyTheme } from 'littlebrand-ui-kit'

// Just provide single colors - everything else is generated!
applyTheme({
  primary: '#8b5cf6',   // Your brand purple
  secondary: '#f59e0b'  // Your brand orange
})

That's it! This generates:

12-step color scales for each color
Dark mode colors automatically
Alpha/transparent versions
All semantic tokens (borders, fills, text, surfaces)

Method 2: CSS Variables

Override specific variables in your CSS:

/* your-overrides.css */
:root {
  /* Change main colors */
  --lb-fill-primary-normal: #8b5cf6;
  --lb-border-primary-normal: #8b5cf6;
  --lb-text-primary-normal: #8b5cf6;
  
  /* Change typography - separate fonts for different contexts */
  --lb-font-heading: 'Playfair Display', serif;
  --lb-font-body: 'Inter', sans-serif;  
  --lb-font-label: 'Inter', sans-serif;  /* UI elements */
  --lb-font-size-base: 15px;
  
  /* Change border radius */
  --lb-radius-md: 12px;
}

Method 3: Advanced SASS Customization

For build-time generation with full control:

// custom-theme.sass
@use 'littlebrand-ui-kit/src/styles/color-generator' as gen

// Generate from single colors
$my-colors: (
  'primary': #8b5cf6,
  'secondary': #f59e0b
)

@each $name, $color in $my-colors
  $scale: gen.generate-scale($color)
  // ... generates everything

📚 Customization Guide

See CUSTOMIZATION.md for detailed customization options including:

Color generation options
Typography customization
Border radius
Component-specific overrides

🧩 Components

Form Components

LbInput - Text input with validation states
LbTextarea - Multi-line text input
LbSelect - Dropdown select
LbCheckbox - Checkbox with label
LbRadio - Radio button groups
LbSwitch - Toggle switch
LbFormField - Form field wrapper with label
LbChatInput - Chat/LLM-style input with auto-grow and actions

Button Components

LbButton - Multiple variants (filled, outline, ghost, tonal, link)
LbSegmentButton - Segmented button group

Feedback Components

LbDialog - Modal dialog
LbSnackbar - Toast notifications
LbBottomSheet - Mobile-style bottom sheet

LbNavigationBar - App navigation bar

Display Components

LbAvatar - User avatars
LbBadge - Status badges
LbChip - Versatile chips for actions, filtering, and input (assist/filter/input types with tonal/filled/outline variants)
LbDivider - Content dividers
LbProgress - Progress indicators

Utility Components

LbPopover - Popover container
LbMenu - Dropdown menus
LbDropdown - Generic dropdown

🌙 Dark Mode

Full dark mode support is built-in! Simply activate it with the dark class or data-theme attribute:

<!-- Using class -->
<body class="dark">
  <!-- All components now use dark mode colors -->
</body>

<!-- Using data attribute -->
<html data-theme="dark">
  <!-- All components now use dark mode colors -->
</html>

Dark mode automatically switches all 312 tokens to properly optimized dark values.

🎯 Color System Features

Automatic Generation

From ONE color, get:

12 Light Mode Steps: From subtle backgrounds to high-contrast text
12 Dark Mode Steps: Optimized for dark backgrounds
12 Alpha Light Steps: Transparent versions for overlays
12 Alpha Dark Steps: Dark mode transparencies
20+ Semantic Tokens: Border, fill, text, and surface variants

Saturation Curves

Choose the mood of your colors:

// Natural (default) - balanced
applyTheme({ primary: '#6366f1' }, 'natural')

// Vivid - more saturated, bold
applyTheme({ primary: '#6366f1' }, 'vivid')

// Muted - less saturated, subtle
applyTheme({ primary: '#6366f1' }, 'muted')

📖 Examples

Complete Theme Change

import { applyTheme } from 'littlebrand-ui-kit'

// Corporate blue theme
applyTheme({
  primary: '#0066cc',
  secondary: '#6b7280',
  success: '#10b981',
  warning: '#f59e0b',
  error: '#ef4444'
})

// Playful purple theme
applyTheme({
  primary: '#8b5cf6',
  secondary: '#ec4899',
  success: '#10b981'
}, 'vivid') // Use vivid curve for more saturation

Override Specific Variables

:root {
  /* Typography - Three independent font families */
  --lb-font-heading: 'Playfair Display', serif;
  --lb-font-body: 'Roboto', sans-serif;
  --lb-font-label: 'Inter', sans-serif;
  
  /* Font sizes and weights */
  --lb-font-size-sm: 13px;
  --lb-font-size-base: 15px;
  --lb-font-size-lg: 18px;
  --lb-font-weight-regular: 400;
  --lb-font-weight-medium: 500;
  --lb-font-weight-bold: 700;
  
  /* Border Radius */
  --lb-radius-sm: 4px;
  --lb-radius-md: 8px;
  --lb-radius-lg: 12px;
  --lb-radius-full: 9999px;
  
  /* Shadows */
  --lb-shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
  --lb-shadow-md: 0 4px 6px rgba(0,0,0,0.07);
  --lb-shadow-lg: 0 10px 15px rgba(0,0,0,0.1);
}

🤖 AI Assistant Integration

LittleBrand UI Kit includes an integrated Model Context Protocol (MCP) server that enables AI assistants like Claude to accurately discover components, design tokens, and generate code without hallucinating prop names or variable names.

Why Use the MCP Server?

Problem: LLMs often guess wrong component props and design token variable names.

Solution: The MCP server provides a source of truth that AI assistants can query for:

Exact component prop names, types, and options
Design token variable names and values
Usage examples and documentation
Code generation with accurate syntax

Quick Setup

The MCP server is automatically included when you install littlebrand-ui-kit. All dependencies are bundled, so no additional installation is needed!

For Claude Code (Project-Specific)

Create .claude/config.json in your project root:

{
  "mcpServers": {
    "littlebrand-ui-kit": {
      "command": "node",
      "args": [
        "./node_modules/littlebrand-ui-kit/mcp-server/dist/index.js"
      ]
    }
  }
}

Then restart Claude Code. The MCP server will load automatically and provide access to all LittleBrand components and tokens.

For Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "littlebrand-ui-kit": {
      "command": "node",
      "args": [
        "/absolute/path/to/your-project/node_modules/littlebrand-ui-kit/mcp-server/dist/index.js"
      ]
    }
  }
}

Replace /absolute/path/to/your-project/ with your actual project path.

For Global Access (Optional)

If you want the MCP server available across all projects, you can reference it from any project where littlebrand-ui-kit is installed, or install it globally:

npm install -g littlebrand-ui-kit

Then use the global path in your config.

Available MCP Tools

Component Discovery: lb_list_components, lb_search_components, lb_get_component_info
Design Tokens: lb_list_tokens, lb_search_tokens, lb_get_token_info
Code Generation: lb_generate_component_example, lb_generate_theme_config
Documentation: lb_get_installation_guide, lb_get_theming_guide

Testing the MCP Server

After setup, try asking your AI assistant:

"Show me all available LittleBrand components"
"How do I use the LbButton component?"
"What spacing tokens are available?"
"Generate a form with email input and submit button"

Learn More

See the MCP Server README for detailed documentation and troubleshooting.

🛠️ Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build

# Preview production build
npm run preview

📄 License

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📚 Documentation

Customization Guide - Complete customization documentation
CSS Variables Reference - All 312 customizable variables
Typography Guide - Font setup and typography
Override Template - Ready-to-use starter file

🔗 Links

Built with ❤️ using Vue 3, Vite, and SASS