Getting Started

Theming

baseui-cn uses CSS custom properties for theming. Tokens are defined as raw color values and mapped into Tailwind utilities through @theme, so utility classes like bg-primary/50.

CSS variables

Added to your configured stylesheet, such as app/globals.css or src/styles.css, by npx baseui-cn init.

app/globals.css

@layer base {
  :root {
    --background: oklch(1 0 0);
    --foreground: oklch(0.141 0 0);
    --card: oklch(1 0 0);
    --card-foreground: oklch(0.141 0 0);
    --popover: oklch(1 0 0);
    --popover-foreground: oklch(0.141 0 0);
    --primary: oklch(0.21 0 0);
    --primary-foreground: oklch(0.985 0 0);
    --secondary: oklch(0.967 0 0);
    --secondary-foreground: oklch(0.21 0 0);
    --muted: oklch(0.967 0 0);
    --muted-foreground: oklch(0.552 0 0);
    --accent: oklch(0.967 0 0);
    --accent-foreground: oklch(0.21 0 0);
    --destructive: oklch(0.577 0.245 27.325);
    --destructive-foreground: oklch(0.985 0 0);
    --success: oklch(0.627 0.154 144.33);
    --success-foreground: oklch(0.985 0 0);
    --warning: oklch(0.769 0.188 70.08);
    --warning-foreground: oklch(0.21 0 0);
    --info: oklch(0.623 0.188 259.81);
    --info-foreground: oklch(0.985 0 0);
    --border: oklch(0.922 0 0);
    --input: oklch(0.922 0 0);
    --ring: oklch(0.708 0 0);
    --radius: 0.5rem;
  }

  .dark {
    --background: oklch(0.141 0 0);
    --foreground: oklch(0.985 0 0);
    --card: oklch(0.141 0 0);
    --card-foreground: oklch(0.985 0 0);
    --popover: oklch(0.141 0 0);
    --popover-foreground: oklch(0.985 0 0);
    --primary: oklch(0.985 0 0);
    --primary-foreground: oklch(0.21 0 0);
    --secondary: oklch(0.269 0 0);
    --secondary-foreground: oklch(0.985 0 0);
    --muted: oklch(0.269 0 0);
    --muted-foreground: oklch(0.708 0 0);
    --accent: oklch(0.269 0 0);
    --accent-foreground: oklch(0.985 0 0);
    --destructive: oklch(0.396 0.141 25.723);
    --destructive-foreground: oklch(0.985 0 0);
    --success: oklch(0.525 0.118 145.16);
    --success-foreground: oklch(0.985 0 0);
    --warning: oklch(0.645 0.149 69.84);
    --warning-foreground: oklch(0.21 0 0);
    --info: oklch(0.546 0.147 258.34);
    --info-foreground: oklch(0.985 0 0);
    --border: oklch(1 0 0 / 10%);
    --input: oklch(1 0 0 / 15%);
    --ring: oklch(0.552 0 0);
  }
}

`destructive`, `success`, `warning`, and `info` are all first-class semantic tokens. Use them for badges, toasts, alerts, and status-heavy surfaces instead of hard-coding raw color values inside components.

Tailwind v4 theme mapping

Add this @theme block so utilities like bg-primary and text-muted-foreground resolve to your variables.

app/globals.css

@import "tailwindcss";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

Customizing your theme

Override any variable in your :root. Changes propagate to every component automatically.

/* Blue primary */
:root {
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
}

/* Rounder corners */
:root {
  --radius: 0.75rem;
}

/* Green brand */
:root {
  --primary: 142.1 76.2% 36.3%;
  --primary-foreground: 355.7 100% 97.3%;
}

/* Custom status colors */
:root {
  --success: oklch(0.7 0.16 150);
  --success-foreground: oklch(0.985 0 0);
  --warning: oklch(0.8 0.16 80);
  --warning-foreground: oklch(0.21 0 0);
  --info: oklch(0.68 0.14 250);
  --info-foreground: oklch(0.985 0 0);
}

Dark mode

Uses the .dark class strategy. Add the class to your <html> element. We recommend next-themes for automatic system preference detection.

app/layout.tsx

import { ThemeProvider } from "next-themes"

export default function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

pnpm add next-themes

Base UI data attributes

Base UI applies these attributes to components. Use them in Tailwind for state-based styling.

data-[open]Overlay or disclosure is open

data-[closed]Overlay is closed — use for exit animations

data-[checked]Checkbox, switch, or radio is checked

data-[indeterminate]Checkbox is indeterminate

data-[disabled]Component is disabled

data-[highlighted]List item is focused/highlighted

data-[selected]Select item is selected

data-[starting-style]Entry animation start state

data-[side=top|bottom|left|right]Floating element placement

/* Use data attributes for state-based Tailwind classes */
className="data-open:opacity-100 data-closed:opacity-0 transition-opacity"
className="data-checked:bg-primary data-checked:border-primary"
className="data-highlighted:bg-accent data-highlighted:text-accent-foreground"

Accordion & Collapsible animations

Add these keyframes to your main stylesheet for smooth height transitions.

app/globals.css

@layer utilities {
  @keyframes accordion-down {
    from { height: 0; opacity: 0; }
    to { height: var(--accordion-content-height); opacity: 1; }
  }
  @keyframes accordion-up {
    from { height: var(--accordion-content-height); opacity: 1; }
    to { height: 0; opacity: 0; }
  }

  .animate-accordion-down {
    animation: accordion-down 0.2s ease-out;
  }
  .animate-accordion-up {
    animation: accordion-up 0.2s ease-out;
  }
}

← Installation LLM usage →