> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cedarcopilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Styling

> Customize the appearance of Cedar-OS components

Cedar-OS provides comprehensive styling options through the `stylingSlice` and integrates seamlessly with Tailwind CSS. This guide covers how to customize the appearance of Cedar components and ensure proper Tailwind configuration.

## Tailwind CSS Setup

Cedar-OS components use Tailwind CSS for styling. To ensure all Cedar styles work correctly, you need to configure Tailwind to scan Cedar's component files.

### Tailwind 4.0+ Configuration

If you're using Tailwind CSS 4.0 or later, add the following `@source` directive to your main CSS file:

```css theme={null}
/* app/globals.css or your main CSS file */
@import 'tailwindcss';

/* Add Cedar-OS components to Tailwind's content sources */
@source "../node_modules/cedar-os/**/*.{js,ts,jsx,tsx}";
```

### Tailwind 3.x Configuration

For Tailwind CSS 3.x, add Cedar's paths to your `tailwind.config.js`:

```javascript theme={null}
// tailwind.config.js
module.exports = {
	content: [
		// Your app's content paths
		'./src/pages/**/*.{js,ts,jsx,tsx,mdx}',
		'./src/components/**/*.{js,ts,jsx,tsx,mdx}',
		'./src/app/**/*.{js,ts,jsx,tsx,mdx}',
		'./src/lib/**/*.{js,ts,jsx,tsx,mdx}',
		'./src/**/*.{js,ts,jsx,tsx}',

		// Add Cedar-OS component paths
		'./node_modules/cedar-os/**/*.{js,ts,jsx,tsx}',
	],
	// ... rest of your config
};
```

## Using the Styling Slice

Cedar-OS includes a `stylingSlice` that manages global styling configuration for all Cedar components. This allows you to customize colors, dark mode, and other visual properties across your entire application.

### Accessing Styling State

```tsx theme={null}
import { useCedarStore } from 'cedar-os';

function MyComponent() {
	const { styling, setStyling, toggleDarkMode } = useCedarStore();

	return (
		<div>
			<p>Current theme: {styling.darkMode ? 'Dark' : 'Light'}</p>
			<p>Primary color: {styling.color}</p>
			<button onClick={toggleDarkMode}>Toggle Dark Mode</button>
		</div>
	);
}
```

### Styling Configuration

The styling slice provides the following configuration options:

```typescript theme={null}
interface StylingConfig {
	darkMode: boolean; // Enable/disable dark mode
	color: string; // Primary color (hex format)
	secondaryColor: string; // Secondary color (hex format)
	accentColor: string; // Accent color (hex format)
}
```

### Setting Custom Colors

You can update the color scheme programmatically:

```tsx theme={null}
import { useCedarStore } from 'cedar-os';

function ThemeCustomizer() {
	const { setStyling } = useCedarStore();

	const applyBrandColors = () => {
		setStyling({
			color: '#3B82F6', // Blue primary
			secondaryColor: '#1E40AF', // Darker blue
			accentColor: '#F59E0B', // Amber accent
		});
	};

	const applyDarkTheme = () => {
		setStyling({
			darkMode: true,
			color: '#6366F1', // Indigo for dark mode
			secondaryColor: '#4F46E5',
			accentColor: '#EC4899', // Pink accent
		});
	};

	return (
		<div>
			<button onClick={applyBrandColors}>Apply Brand Colors</button>
			<button onClick={applyDarkTheme}>Apply Dark Theme</button>
		</div>
	);
}
```

## Component-Level Styling

### Using Styled Components

Cedar components automatically respond to the global styling configuration. For example, the chat components will use your configured colors:

```tsx theme={null}
import { FloatingCedarChat } from '@/chatComponents/FloatingCedarChat';
import { useCedarStore } from 'cedar-os';

function StyledChat() {
	const { setStyling } = useCedarStore();

	// Set custom colors before rendering
	useEffect(() => {
		setStyling({
			color: '#8B5CF6', // Purple
			secondaryColor: '#7C3AED',
			accentColor: '#F97316', // Orange
		});
	}, []);

	return <FloatingCedarChat side='right' title='Support Chat' />;
}
```

### CSS Variables

Cedar-OS components use CSS variables that integrate with Tailwind's design system. These variables are automatically updated when you change the styling configuration:

```css theme={null}
/* These variables are set by Cedar-OS */
:root {
	--cedar-primary: /* Your primary color */ ;
	--cedar-secondary: /* Your secondary color */ ;
	--cedar-accent: /* Your accent color */ ;
	--cedar-background: /* Background color based on theme */ ;
	--cedar-foreground: /* Text color based on theme */ ;
}
```

## Utility Functions

Cedar-OS provides several utility functions for working with colors:

### Color Manipulation

```tsx theme={null}
import {
	desaturateColor,
	getShadedColor,
	getLightenedColor,
	getTextColorForBackground,
} from 'cedar-os';

// Desaturate a color (reduce vibrancy)
const mutedBlue = desaturateColor('#3B82F6');

// Create a darker shade
const darkBlue = getShadedColor('#3B82F6', 0.2); // 20% darker

// Create a lighter tint
const lightBlue = getLightenedColor('#3B82F6', 0.3); // 30% lighter

// Get appropriate text color for a background
const textColor = getTextColorForBackground('#3B82F6'); // Returns white or black
```

### Class Name Utilities

Cedar uses the `cn` utility (similar to `clsx`) for combining class names:

```tsx theme={null}
import { cn } from 'cedar-os';

function MyComponent({ className, isActive }) {
	return (
		<div
			className={cn(
				'base-styles px-4 py-2',
				isActive && 'bg-blue-500 text-white',
				className
			)}>
			Content
		</div>
	);
}
```

## Dark Mode Support

Cedar-OS components automatically support dark mode through Tailwind's dark mode classes. When you toggle dark mode using `toggleDarkMode()`, all Cedar components will update their appearance.

### Implementing Dark Mode Toggle

```tsx theme={null}
import { useCedarStore } from 'cedar-os';
import { Moon, Sun } from 'lucide-react';

function DarkModeToggle() {
	const { styling, toggleDarkMode } = useCedarStore();

	useEffect(() => {
		// Apply dark mode class to document
		if (styling.darkMode) {
			document.documentElement.classList.add('dark');
		} else {
			document.documentElement.classList.remove('dark');
		}
	}, [styling.darkMode]);

	return (
		<button
			onClick={toggleDarkMode}
			className='p-2 rounded-lg bg-gray-200 dark:bg-gray-800'>
			{styling.darkMode ? <Sun /> : <Moon />}
		</button>
	);
}
```

## Best Practices

1. **Configure Tailwind First**: Always ensure your Tailwind configuration includes Cedar's component paths before using Cedar components.

2. **Set Colors Early**: Configure your color scheme early in your app's lifecycle, preferably in your root component:

   ```tsx theme={null}
   function App() {
   	const { setStyling } = useCedarStore();

   	useEffect(() => {
   		setStyling({
   			color: '#YourBrandColor',
   			secondaryColor: '#YourSecondaryColor',
   			accentColor: '#YourAccentColor',
   		});
   	}, []);

   	return <YourApp />;
   }
   ```

3. **Consistent Theme**: Use the styling slice to maintain consistent theming across all Cedar components rather than overriding styles individually.

4. **Responsive Dark Mode**: Always test your color choices in both light and dark modes to ensure good contrast and readability.

## Troubleshooting

### Styles Not Applying

If Cedar component styles aren't working:

1. **Check Tailwind Config**: Ensure Cedar paths are included in your Tailwind configuration
2. **Clear Cache**: Try clearing your build cache and rebuilding
3. **Check CSS Import**: Make sure you're importing your global CSS file that includes Tailwind directives
4. **Verify Installation**: Ensure both `cedar-os` and components are properly installed

### Dark Mode Issues

If dark mode isn't working:

1. **Check HTML Class**: Ensure the `dark` class is being applied to your `<html>` element
2. **Tailwind Dark Mode**: Verify your Tailwind config uses `class` strategy for dark mode:
   ```javascript theme={null}
   module.exports = {
   	darkMode: 'class',
   	// ... rest of config
   };
   ```

## Next Steps

* Explore [component customization](/customising/customising-cedar) for more advanced styling options
* Learn about [custom message rendering](/chat/custom-message-rendering) to style chat messages
* Check out the [Cedar Playground](https://cedarcopilot.com/examples/cedar-playground) to see styling in action