Design System

Bao UI uses a token-first design system built on Tailwind CSS v4 for consistent theming and customization.

Design Tokens

Colors

Bao UI uses a semantic color system:

:root {
  --color-background: hsl(0 0% 100%);
  --color-foreground: hsl(222.2 84% 4.9%);
  --color-border: hsl(214.3 31.8% 91.4%);
  --color-primary: hsl(222.2 47.4% 11.2%);
  --color-destructive: hsl(0 84.2% 60.2%);
}

Typography

Font families and sizes:

--font-sans: system-ui, sans-serif;
--font-mono: ui-monospace, 'SF Mono', 'Consolas', monospace;
 
--text-sm: 0.875rem;
--text-base: 1rem;
--text-lg: 1.125rem;
--text-xl: 1.25rem;

Spacing

Consistent spacing scale:

--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px */

Border Radius

Rounded corner scale:

--radius-sm: 0.125rem; /* 2px */
--radius: 0.25rem; /* 4px */
--radius-md: 0.375rem; /* 6px */
--radius-lg: 0.5rem; /* 8px */

Tailwind Plugin

Install and configure the Bao UI Tailwind plugin:

// tailwind.config.js
import { plugin } from '@bao-ui/tokens/tailwind'
 
export default {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  plugins: [plugin],
}

This adds custom utilities and component classes:

/* Button variants */
.btn-default {
  /* ... */
}
.btn-outline {
  /* ... */
}
.btn-destructive {
  /* ... */
}
 
/* Utilities */
.text-foreground {
  color: hsl(var(--foreground));
}
.bg-background {
  background-color: hsl(var(--background));
}
.border-border {
  border-color: hsl(var(--border));
}

Theming

CSS Custom Properties

Override design tokens with CSS custom properties:

:root {
  /* Override primary color */
  --color-primary: hsl(210 40% 98%);
  --color-primary-foreground: hsl(222.2 47.4% 11.2%);
 
  /* Override border radius */
  --radius: 0.5rem;
}

Dark Mode

Bao UI supports dark mode through CSS custom properties:

@media (prefers-color-scheme: dark) {
  :root {
    --color-background: hsl(222.2 47.4% 11.2%);
    --color-foreground: hsl(213 31% 91%);
    --color-border: hsl(214.3 31.8% 22.4%);
  }
}
 
/* Or with class-based dark mode */
.dark {
  --color-background: hsl(222.2 47.4% 11.2%);
  --color-foreground: hsl(213 31% 91%);
  --color-border: hsl(214.3 31.8% 22.4%);
}

Component Customization

Customize individual components:

/* Custom button styles */
.my-button {
  --button-bg: hsl(210 100% 50%);
  --button-fg: white;
  --button-radius: 1rem;
}

Animation

Transitions

Smooth transitions with motion preferences:

* {
  transition-duration: 150ms;
  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}
 
@media (prefers-reduced-motion: reduce) {
  * {
    transition-duration: 0ms;
  }
}

Keyframes

Common animation keyframes:

@keyframes fade-in {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}
 
@keyframes slide-up {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

Best Practices

Consistent Spacing

Use the spacing scale for margins, padding, and gaps:

<div className="p-4 m-6 gap-2">
  {/* Uses --space-4, --space-6, --space-2 */}
</div>

Semantic Colors

Use semantic color names instead of literal colors:

// Good
<Button className="bg-destructive text-destructive-foreground">
 
// Avoid
<Button className="bg-red-500 text-white">

Responsive Design

Use responsive utilities for different screen sizes:

<Button className="text-sm md:text-base lg:text-lg">Responsive text</Button>

Tooltip Examples