brand-os-core
v1.0.3
Published
Brand enforcement runtime for AI-generated UI. Ensures your aesthetic is preserved.
Downloads
18
Maintainers
caboo-designReadme
brand-os-core
Stop AI from generating generic UI. Brand-OS ensures every component matches your exact design system.
Brand-OS is a lightweight (27KB) brand-enforcement runtime that makes it impossible for AI tools to generate off-brand UI components. It works with Claude Code, Cursor, GitHub Copilot, and any AI coding assistant.
🚀 Quick Start (60 seconds)
Option 1: Create New App (Recommended)
npx create-brand-os-app my-app
cd my-app
npm run devOption 2: Add to Existing Project
npm install brand-os-coreFeatures
✅ Token-Only Styling - Forces AI to use your CSS variables, never hardcoded colors
✅ Glass Morphism Built-in - Beautiful frosted glass effects out of the box
✅ Type-Safe - Full TypeScript support
✅ Tiny Bundle - Only 27KB total, tree-shakeable
✅ Framework Agnostic - Works with Next.js, Vite, CRA, or any React app
✅ AI-Ready - Works with Claude, Cursor, Copilot out of the box
Basic Usage
1. Add Provider
// app/layout.tsx or App.tsx
import { BrandOSProvider } from 'brand-os-core';
export default function RootLayout({ children }) {
return (
<html>
<body>
<BrandOSProvider config={{
nano: {
// Your brand colors
'--brand-primary': '#3B82F6',
'--brand-secondary': '#8B5CF6',
// Glass morphism
'--glass-bg': 'rgba(255, 255, 255, 0.6)',
'--glass-blur': '40px',
'--glass-border': 'rgba(255, 255, 255, 0.2)',
// Your shadows
'--shadow-xl': '0 20px 25px -5px rgba(0, 0, 0, 0.1)'
}
}}>
{children}
</BrandOSProvider>
</body>
</html>
);
}2. Use Components
import { PageShell, Resolved } from 'brand-os-core';
import { CardShell, MetricItem } from 'brand-os-core/primitives';
export default function Dashboard() {
return (
<PageShell layout="dashboard">
<PageShell.Header>
<h1>My Dashboard</h1>
</PageShell.Header>
<PageShell.Metrics cols={4}>
<CardShell hover>
<MetricItem
value="$125,000"
label="Revenue"
change="+12%"
trend="up"
/>
</CardShell>
</PageShell.Metrics>
</PageShell>
);
}AI Tool Setup
Make AI generate perfect Brand-OS components automatically:
For Claude Code
curl -O https://raw.githubusercontent.com/Caboo-intelligence/brand-os/main/CLAUDE.mdFor Cursor
curl -O https://raw.githubusercontent.com/Caboo-intelligence/brand-os/main/.cursorrulesNow when you ask AI to generate UI, it will automatically use Brand-OS components and respect your design tokens!
Core Components
Primitives
Token-locked building blocks that enforce your brand:
import {
CardShell, // Glass morphism cards
Panel, // Basic panels
Stack, // Vertical layouts
Grid, // Grid layouts
MetricItem, // Metric displays
Sparkline, // Mini charts
Badge, // Status indicators
TargetBand // Progress bars
} from 'brand-os-core/primitives';PageShell
Page-level wrapper that enforces layout and spacing:
<PageShell
layout="dashboard" // dashboard | analytics | settings | landing
density="normal" // compact | normal | spacious
pattern="gradient" // gradient | dots | grid | aurora
>
<PageShell.Header>{/* Page header */}</PageShell.Header>
<PageShell.Metrics>{/* Metric cards */}</PageShell.Metrics>
<PageShell.Main>{/* Main content */}</PageShell.Main>
<PageShell.Sidebar>{/* Optional sidebar */}</PageShell.Sidebar>
</PageShell>Resolved Components
Dynamic component resolution from intents:
<Resolved intent={{
type: "stat-card",
data: {
title: "Revenue",
value: 125000,
change: 12.5,
trend: "up"
}
}} />Token System
Brand-OS uses CSS variables (tokens) for all styling. No hardcoded colors allowed.
Required Tokens
/* Brand Colors */
--brand-primary: #3B82F6;
--brand-secondary: #8B5CF6;
--brand-accent: #10B981;
/* Glass Morphism */
--glass-bg: rgba(255, 255, 255, 0.6);
--glass-border: rgba(255, 255, 255, 0.2);
--glass-blur: 40px;
/* Text Colors */
--text-primary: #111827;
--text-secondary: #6B7280;
--text-tertiary: #9CA3AF;
/* Backgrounds */
--bg-primary: #FFFFFF;
--bg-secondary: #F9FAFB;
--bg-tertiary: #F3F4F6;Real Example
import { PageShell } from 'brand-os-core';
import { CardShell, MetricItem, Grid } from 'brand-os-core/primitives';
const metrics = [
{ label: "Revenue", value: "$125K", change: "+12%", trend: "up" },
{ label: "Orders", value: "1,234", change: "+8%", trend: "up" },
{ label: "Customers", value: "456", change: "+23%", trend: "up" },
{ label: "Growth", value: "15.3%", change: "+2.1%", trend: "up" }
];
export default function Dashboard() {
return (
<PageShell layout="dashboard">
<PageShell.Header>
<h1>Sales Dashboard</h1>
</PageShell.Header>
<PageShell.Metrics cols={4}>
{metrics.map((metric, i) => (
<CardShell key={i} hover>
<MetricItem {...metric} />
</CardShell>
))}
</PageShell.Metrics>
<PageShell.Main>
<Grid cols={2} gap="normal">
<CardShell padding="large">
{/* Chart component */}
</CardShell>
<CardShell padding="large">
{/* Table component */}
</CardShell>
</Grid>
</PageShell.Main>
</PageShell>
);
}TypeScript Support
Full TypeScript support with exported types:
import type {
BrandConfig,
ComponentIntent,
PageShellProps,
PrimitiveProps
} from 'brand-os-core';Why Brand-OS?
The Problem: When developers use AI tools to generate UI, they get generic Bootstrap/Tailwind components that don't match their brand.
The Solution: Brand-OS enforces your exact design system through:
- Token-only styling (no hardcoded colors)
- Glass morphism effects
- Consistent spacing & typography
- Type-safe components
The Result: AI generates perfect, on-brand UI every time.
Links
License
MIT © Caboo Intelligence
Built with ❤️ by Caboo Intelligence - We make AI understand design.