Theming

Overview

Docyrus UI uses CSS custom properties (variables) with the OKLCH color space for theming. Every component reads its colors, spacing, typography, and shadows from these variables — making full visual customization possible without touching component code.

The theme system is built on top of shadcn/ui theming, extended with additional variables for charts, sidebar, shadows, and tracking.

Color System

All colors use the OKLCH color space for perceptually uniform color manipulation:

:root {
  --background: oklch(1.0000 0 0);
  --foreground: oklch(0.1288 0.0406 264.6952);
  --primary: oklch(0.2077 0.0398 265.7549);
  --primary-foreground: oklch(0.9842 0.0034 247.8575);
  /* ... */
}

.dark {
  --background: oklch(0.1288 0.0406 264.6952);
  --foreground: oklch(0.9842 0.0034 247.8575);
  --primary: oklch(0.9842 0.0034 247.8575);
  --primary-foreground: oklch(0.1288 0.0406 264.6952);
  /* ... */
}

Core Variables

Card & Popover

Sidebar

Charts

Shadows

Shadows use a composable system with individual variables:

:root {
  --shadow-x: 0px;
  --shadow-y: 1px;
  --shadow-blur: 3px;
  --shadow-spread: 0px;
  --shadow-opacity: 0.1;
  --shadow-color: 0 0 0;
}

Pre-composed shadow scales: --shadow-2xs, --shadow-xs, --shadow-sm, --shadow, --shadow-md, --shadow-lg, --shadow-xl, --shadow-2xl.

Typography

Geometry

Dark Mode

Dark mode is activated by adding the dark class to a parent element (typically <html>). Docyrus UI provides DocyThemeProvider for automatic dark/light/system switching:

import { DocyThemeProvider } from '@/lib/theme';

function App({ children }) {
  return (
    <DocyThemeProvider defaultMode="system">
      {children}
    </DocyThemeProvider>
  );
}

Inside components, use the useDocyTheme() hook to access the resolved theme:

import { useDocyTheme } from '@/lib/theme';

function MyComponent() {
  const { isDark, mode, setMode, lang } = useDocyTheme();

  return <div>{isDark ? 'Dark' : 'Light'}</div>;
}

Components automatically adapt to the active theme through CSS variable inheritance. DocyThemeProvider manages the dark class on <html>, persists the preference to localStorage, and listens for system color scheme changes.

Theme Generator

Use the built-in Theme Generator to visually customize your theme:

1. Pick a base color scheme (Slate, Gray, Zinc, Stone, Neutral)
2. Adjust primary accent color with the color picker
3. Set border radius and shadow intensity
4. Preview components in real-time
5. Export the CSS variables to paste into your globals.css

Custom Theme Example

To create a custom theme, override the CSS variables in your globals.css:

@import "tailwindcss";

:root {
  /* Warm orange primary */
  --primary: oklch(0.7690 0.1880 70.0800);
  --primary-foreground: oklch(0.1500 0 0);

  /* Rounded look */
  --radius: 0.75rem;

  /* Softer shadows */
  --shadow-opacity: 0.06;
}

.dark {
  --primary: oklch(0.7690 0.1880 70.0800);
  --primary-foreground: oklch(0.1500 0 0);
  --shadow-opacity: 0.4;
}

Using Theme Values in Components

Access theme variables through Tailwind CSS utilities:

// Background and text
<div className="bg-primary text-primary-foreground" />

// Borders
<div className="border border-border rounded-[var(--radius)]" />

// Shadows
<div className="shadow-md" />

// Custom usage with CSS variable
<div style={{ color: 'var(--chart-1)' }} />

Color Palette Reference

Docyrus UI ships with 5 neutral base palettes:

Each palette provides a complete set of light and dark mode variables.