Theming

Overview

mcoli-ui ships with 5 signature themes designed to give your project a distinct visual identity. Each theme is crafted with MicroClub DNA, combining professional aesthetics with a bold, modern edge.

All themes support both light and dark modes out of the box.

Available Themes

Add a Theme to Your Project

Deploy a theme directly to your project:

Interactive Mode

Running npx mcoli-ui@latest init without arguments launches an interactive theme selector.

Specify a Theme Directly

You can also specify a theme directly:

Available themes: primary, secondary, game-dev, robotics, it

Manual Setup

If you prefer manual control:

src/registry/themes/{themeName}Theme.ts

@theme {
  --color-primary: oklch(70% 0.15 240);
  --color-secondary: oklch(20% 0.15 240);
  /* ... other theme colors */
}

Theme Structure

Each theme follows this structure:

export const themeName = {
  // Border radius values (vary by theme)
  theme: {
    'radius-sm': '0.125rem', // robotics uses tighter radii
    'radius-md': '0.375rem',
    'radius-lg': '0.5rem',
    'radius-xl': '0.75rem',
    'radius-2xl': '1rem', // game-dev uses 1rem
  },
  // Light mode colors
  light: {
    background: '...',
    foreground: '...',
    primary: '...',
    'primary-foreground': '...',
    // ... more colors
  },
  // Dark mode colors
  dark: {
    background: '...',
    foreground: '...',
    primary: '...',
    'primary-foreground': '...',
    // ... more colors
  },
};

Color System

All themes use a consistent color system. Here are all the available CSS variables you can use in your components. Each theme has its own values for light and dark modes.

Sidebar Variables

Sidebar-specific variables for navigation components:

Chart Colors

Colors for data visualization:

Using Colors in Components

In your Tailwind classes, use these tokens as follows:

className = 'text-muted-foreground'; // Uses --muted-foreground
className = 'bg-primary'; // Uses --primary
className = 'border-border'; // Uses --border
className = 'text-destructive'; // Uses --destructive

All colors are available as bg-, text-, border-, and other Tailwind utilities.

Switching Themes

mcoli-ui components use CSS variables tied to theme tokens. To switch themes, re-run the init command with your desired theme:

This updates your registry configuration with the new theme's CSS variables.

Customizing Themes

For advanced customization, you can extend or override any theme:

@theme {
  --color-primary: var(--primary);
  --radius-lg: 1rem;
}

:root {
  --primary: your-custom-color;
}

.dark {
  --primary: your-custom-color;
}

This gives you full control while maintaining consistency across your project.