# Theming
URL: /docs/web/guide/theming
Customize the look and feel of Docyrus UI components with CSS variables and the theme generator.
## 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](https://ui.shadcn.com/docs/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:
```css title="globals.css"
: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
| Variable | Description |
|----------|-------------|
| `--background` | Page/app background |
| `--foreground` | Default text color |
| `--primary` | Primary brand color (buttons, links, active states) |
| `--secondary` | Secondary UI surfaces |
| `--muted` | Subdued backgrounds and borders |
| `--accent` | Highlighted or focused elements |
| `--destructive` | Error/danger actions |
| `--border` | Default border color |
| `--input` | Input field borders |
| `--ring` | Focus ring color |
### Card & Popover
| Variable | Description |
|----------|-------------|
| `--card` | Card background |
| `--card-foreground` | Card text color |
| `--popover` | Popover/dropdown background |
| `--popover-foreground` | Popover text color |
### Sidebar
| Variable | Description |
|----------|-------------|
| `--sidebar` | Sidebar background |
| `--sidebar-foreground` | Sidebar text |
| `--sidebar-primary` | Sidebar active item |
| `--sidebar-accent` | Sidebar hover state |
| `--sidebar-border` | Sidebar border |
### Charts
| Variable | Description |
|----------|-------------|
| `--chart-1` through `--chart-5` | Chart color palette |
### Shadows
Shadows use a composable system with individual variables:
```css
: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
| Variable | Description |
|----------|-------------|
| `--font-sans` | Sans-serif font stack |
| `--font-serif` | Serif font stack |
| `--font-mono` | Monospace font stack |
| `--tracking-normal` | Default letter spacing |
### Geometry
| Variable | Description |
|----------|-------------|
| `--radius` | Base border radius (default: `0.5rem`) |
| `--spacing` | Base spacing unit (default: `0.25rem`) |
## Dark Mode
Dark mode is activated by adding the `dark` class to a parent element (typically ``). Docyrus UI uses the `next-themes` library for automatic dark/light switching:
```tsx
import { ThemeProvider } from 'next-themes';
function App({ children }) {
return (
);
}
```
Components automatically adapt to the active theme through CSS variable inheritance.
## Theme Generator
Use the built-in [Theme Generator](/themes) 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`:
```css title="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:
```tsx
// Background and text
// Borders
// Shadows
// Custom usage with CSS variable
```
## Color Palette Reference
Docyrus UI ships with 5 neutral base palettes:
| Palette | Character |
|---------|-----------|
| **Slate** | Cool blue-gray (default) |
| **Gray** | Pure neutral gray |
| **Zinc** | Warm gray with slight warmth |
| **Stone** | Warm brown-gray |
| **Neutral** | True neutral, no undertone |
Each palette provides a complete set of light and dark mode variables.