# Theming Guide

Complete guide for customizing CCL UI Components with themes and design tokens.

## Table of Contents

- [Available Themes](#available-themes)
- [Basic Theme Usage](#basic-theme-usage)
- [Custom Theme Overrides](#custom-theme-overrides)
- [Design Token Reference](#design-token-reference)
- [Advanced Theming](#advanced-theming)
- [Theme Examples](#theme-examples)
- [Best Practices](#best-practices)

## Available Themes

### 1. Naked Theme (Default)
Clean, minimal design with neutral colors and standard spacing.

```css
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';
```

**Characteristics**:
- Neutral color palette
- Standard border radius
- System font stack
- Consistent spacing scale

### 2. BrandA Theme
Corporate branding with custom colors and enhanced visual hierarchy.

```css
@import '@Crystal-Code-Labs/ccl-ui-components/styles/brandA.css';
```

**Characteristics**:
- Brand-specific color palette
- Enhanced visual contrast
- Custom typography scale
- Refined spacing system

### 3. Custom Themes
Create your own theme by overriding design tokens.

## Basic Theme Usage

### Using Default Theme

```css
/* src/styles.css */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';
```

### Switching to BrandA Theme

```css
/* src/styles.css */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/brandA.css';
```

**Note**: Import order matters. BrandA overrides Naked theme variables.

## Custom Theme Overrides

### Basic Color Overrides

```css
/* src/styles.css */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';

/* Custom primary color */
:root, :host {
  --color-primary-default: #ff6600;
  --color-primary-500: #ff6600;
  --color-primary-600: #e55a00;
  --color-primary-700: #cc4400;
}
```

### Complete Brand Override

```css
/* src/styles.css */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';

/* Custom brand theme */
:host {
  /* Primary colors */
  --color-primary-default: #8b5cf6;
  --color-primary-500: #8b5cf6;
  --color-primary-600: #7c3aed;
  --color-primary-700: #6d28d9;
  
  /* Secondary colors */
  --color-secondary-default: #64748b;
  --color-secondary-500: #64748b;
  --color-secondary-600: #475569;
  
  /* Semantic colors */
  --color-success-default: #10b981;
  --color-warning-default: #f59e0b;
  --color-error-default: #ef4444;
  
  /* Typography */
  --typography-font-family-default: 'Inter', system-ui, sans-serif;
  --typography-font-size-md: 1rem;
  --typography-font-weight-medium: 500;
  
  /* Spacing */
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  
  /* Border radius */
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-xl: 16px;
}
```

### Scoped Theming

Apply different themes to different sections of your application:

```html
<!-- Different themed sections -->
<div class="marketing-section">
  <ccl-button label="Marketing Button"></ccl-button>
</div>

<div class="admin-section">
  <ccl-button label="Admin Button"></ccl-button>
</div>

<div class="user-section">
  <ccl-button label="User Button"></ccl-button>
</div>
```

```css
/* Scoped theme overrides */
.marketing-section {
  --color-primary-default: #f97316; /* Orange theme */
  --radius-md: 20px; /* Rounded corners */
}

.admin-section {
  --color-primary-default: #dc2626; /* Red theme */
  --color-secondary-default: #6b7280;
  --radius-md: 4px; /* Sharp corners */
}

.user-section {
  --color-primary-default: #059669; /* Green theme */
  --color-secondary-default: #10b981;
  --radius-md: 12px; /* Medium rounded */
}
```

## Design Token Reference

### Color Tokens

#### Primary Colors
```css
--color-primary-default: #0055ff;    /* Main primary color */
--color-primary-500: #0055ff;         /* Primary 500 */
--color-primary-600: #0044cc;         /* Primary 600 (darker) */
--color-primary-700: #003399;         /* Primary 700 (darkest) */
--color-primary-400: #3366ff;         /* Primary 400 (lighter) */
--color-primary-300: #6699ff;         /* Primary 300 (lightest) */
```

#### Secondary Colors
```css
--color-secondary-default: #6b7280;  /* Main secondary color */
--color-secondary-500: #6b7280;       /* Secondary 500 */
--color-secondary-600: #4b5563;       /* Secondary 600 (darker) */
--color-secondary-700: #374151;       /* Secondary 700 (darkest) */
--color-secondary-400: #9ca3af;       /* Secondary 400 (lighter) */
--color-secondary-300: #d1d5db;       /* Secondary 300 (lightest) */
```

#### Semantic Colors
```css
--color-success-default: #10b981;    /* Success green */
--color-success-500: #10b981;
--color-success-600: #059669;
--color-success-700: #047857;

--color-warning-default: #f59e0b;    /* Warning orange */
--color-warning-500: #f59e0b;
--color-warning-600: #d97706;
--color-warning-700: #b45309;

--color-error-default: #ef4444;      /* Error red */
--color-error-500: #ef4444;
--color-error-600: #dc2626;
--color-error-700: #b91c1c;
```

#### Neutral Scale
```css
--color-neutral-50: #f9fafb;         /* Lightest gray */
--color-neutral-100: #f3f4f6;
--color-neutral-200: #e5e7eb;
--color-neutral-300: #d1d5db;
--color-neutral-400: #9ca3af;
--color-neutral-500: #6b7280;        /* Middle gray */
--color-neutral-600: #4b5563;
--color-neutral-700: #374151;
--color-neutral-800: #1f2937;
--color-neutral-900: #111827;        /* Darkest gray */
```

#### Background Colors
```css
--color-background-default: #ffffff;  /* Main background */
--color-background-surface: #f9fafb;  /* Surface background */
--color-surface-default: #ffffff;     /* Component surface */
--color-surface-elevated: #ffffff;    /* Elevated surface */
```

### Typography Tokens

#### Font Families
```css
--typography-font-family-default: system-ui, sans-serif;
--typography-font-family-sans: system-ui, sans-serif;
--typography-font-family-serif: Georgia, serif;
--typography-font-family-mono: 'Fira Code', monospace;
```

#### Font Sizes
```css
--typography-font-size-xs: 0.75rem;    /* 12px */
--typography-font-size-sm: 0.875rem;   /* 14px */
--typography-font-size-md: 1rem;       /* 16px */
--typography-font-size-lg: 1.125rem;   /* 18px */
--typography-font-size-xl: 1.25rem;    /* 20px */
--typography-font-size-2xl: 1.5rem;    /* 24px */
--typography-font-size-3xl: 1.875rem;  /* 30px */
--typography-font-size-4xl: 2.25rem;   /* 36px */
```

#### Font Weights
```css
--typography-font-weight-light: 300;
--typography-font-weight-regular: 400;
--typography-font-weight-medium: 500;
--typography-font-weight-semibold: 600;
--typography-font-weight-bold: 700;
--typography-font-weight-extrabold: 800;
```

#### Line Heights
```css
--typography-line-height-tight: 1.25;
--typography-line-height-normal: 1.5;
--typography-line-height-relaxed: 1.75;
```

### Spacing Tokens

```css
--spacing-0: 0;                       /* 0px */
--spacing-1: 0.25rem;                 /* 4px */
--spacing-2: 0.5rem;                  /* 8px */
--spacing-3: 0.75rem;                 /* 12px */
--spacing-4: 1rem;                    /* 16px */
--spacing-5: 1.25rem;                 /* 20px */
--spacing-6: 1.5rem;                  /* 24px */
--spacing-8: 2rem;                    /* 32px */
--spacing-10: 2.5rem;                 /* 40px */
--spacing-12: 3rem;                   /* 48px */
--spacing-16: 4rem;                   /* 64px */
--spacing-20: 5rem;                   /* 80px */
--spacing-24: 6rem;                   /* 96px */
```

### Border Radius Tokens

```css
--radius-none: 0;                     /* No radius */
--radius-sm: 0.25rem;                 /* 4px */
--radius-md: 0.375rem;                /* 6px */
--radius-lg: 0.5rem;                  /* 8px */
--radius-xl: 0.75rem;                 /* 12px */
--radius-2xl: 1rem;                   /* 16px */
--radius-full: 9999px;                /* Fully rounded */
```

### Motion Tokens

```css
--motion-fast: 150ms;                 /* Fast animations */
--motion-default: 200ms;              /* Default animations */
--motion-slow: 300ms;                 /* Slow animations */
--motion-slower: 500ms;               /* Slower animations */
```

### Shadow Tokens

```css
--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
--shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
```

## Advanced Theming

### Dark Mode Support

```css
/* Light mode (default) */
:host {
  --color-background-default: #ffffff;
  --color-surface-default: #f9fafb;
  --color-text-default: #111827;
  --color-text-secondary: #6b7280;
}

/* Dark mode */
@media (prefers-color-scheme: dark) {
  :host {
    --color-background-default: #111827;
    --color-surface-default: #1f2937;
    --color-text-default: #f9fafb;
    --color-text-secondary: #9ca3af;
  }
}

/* Manual dark mode toggle */
.dark-mode {
  --color-background-default: #111827;
  --color-surface-default: #1f2937;
  --color-text-default: #f9fafb;
  --color-text-secondary: #9ca3af;
}
```

### Responsive Theming

```css
/* Mobile-first responsive theming */
:host {
  --spacing-md: 0.75rem;              /* Smaller spacing on mobile */
  --typography-font-size-md: 0.875rem;
  --radius-md: 0.25rem;
}

@media (min-width: 768px) {
  :host {
    --spacing-md: 1rem;               /* Standard spacing on tablet */
    --typography-font-size-md: 1rem;
    --radius-md: 0.375rem;
  }
}

@media (min-width: 1024px) {
  :host {
    --spacing-md: 1.25rem;            /* Larger spacing on desktop */
    --typography-font-size-md: 1.125rem;
    --radius-md: 0.5rem;
  }
}
```

### Component-Specific Theming

```css
/* Override specific component styles */
:host {
  /* Button-specific overrides */
  --button-primary-bg: var(--color-primary-default);
  --button-primary-hover: var(--color-primary-600);
  --button-primary-text: #ffffff;
  
  /* Input-specific overrides */
  --input-border-color: var(--color-neutral-300);
  --input-border-focus: var(--color-primary-default);
  --input-bg: var(--color-surface-default);
  
  /* Modal-specific overrides */
  --modal-backdrop: rgba(0, 0, 0, 0.5);
  --modal-bg: var(--color-surface-default);
  --modal-shadow: var(--shadow-xl);
}
```

## Theme Examples

### Corporate Theme

```css
/* Corporate blue theme */
:root, :host {
  --color-primary-default: #1e40af;
  --color-primary-500: #1e40af;
  --color-primary-600: #1d4ed8;
  --color-primary-700: #1e3a8a;
  
  --color-secondary-default: #64748b;
  --color-secondary-500: #64748b;
  --color-secondary-600: #475569;
  
  --typography-font-family-default: 'Inter', system-ui, sans-serif;
  --typography-font-weight-medium: 500;
  
  --radius-md: 6px;
  --radius-lg: 8px;
  
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
}
```

### Creative Theme

```css
/* Creative purple theme */
:root, :host {
  --color-primary-default: #8b5cf6;
  --color-primary-500: #8b5cf6;
  --color-primary-600: #7c3aed;
  --color-primary-700: #6d28d9;
  
  --color-secondary-default: #ec4899;
  --color-secondary-500: #ec4899;
  --color-secondary-600: #db2777;
  
  --typography-font-family-default: 'Poppins', system-ui, sans-serif;
  --typography-font-weight-medium: 600;
  
  --radius-md: 12px;
  --radius-lg: 16px;
  --radius-xl: 20px;
  
  --spacing-md: 1.25rem;
  --spacing-lg: 2rem;
}
```

### Minimal Theme

```css
/* Minimal gray theme */
:root, :host {
  --color-primary-default: #374151;
  --color-primary-500: #374151;
  --color-primary-600: #1f2937;
  --color-primary-700: #111827;
  
  --color-secondary-default: #9ca3af;
  --color-secondary-500: #9ca3af;
  --color-secondary-600: #6b7280;
  
  --typography-font-family-default: 'Helvetica Neue', system-ui, sans-serif;
  --typography-font-weight-medium: 400;
  
  --radius-md: 2px;
  --radius-lg: 4px;
  
  --spacing-md: 0.875rem;
  --spacing-lg: 1.25rem;
}
```

## Best Practices

### 1. Token Organization

```css
/* Organize tokens by category */
:host {
  /* Colors */
  --color-primary-default: #0055ff;
  --color-secondary-default: #6b7280;
  
  /* Typography */
  --typography-font-family-default: system-ui, sans-serif;
  --typography-font-size-md: 1rem;
  
  /* Spacing */
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  
  /* Border radius */
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
}
```

### 2. Consistent Naming

```css
/* Use consistent naming conventions */
:host {
  /* Good: Consistent naming */
  --color-primary-default: #0055ff;
  --color-primary-500: #0055ff;
  --color-primary-600: #0044cc;
  
  /* Bad: Inconsistent naming */
  --primary-color: #0055ff;
  --primary-500: #0055ff;
  --primaryDark: #0044cc;
}
```

### 3. Fallback Values

```css
/* Provide fallback values */
:host {
  --color-primary-default: #0055ff;
  --color-primary-500: var(--color-primary-default, #0055ff);
  --color-primary-600: var(--color-primary-500, #0044cc);
}
```

### 4. Theme Validation

```css
/* Validate theme tokens */
:host {
  /* Ensure color contrast ratios meet accessibility standards */
  --color-primary-default: #0055ff; /* Good contrast on white */
  --color-text-default: #111827;    /* Good contrast on white */
  
  /* Test with different backgrounds */
  --color-background-default: #ffffff;
  --color-background-surface: #f9fafb;
}
```

### 5. Performance Considerations

```css
/* Use CSS custom properties efficiently */
:host {
  /* Good: Reuse base tokens */
  --color-primary-default: #0055ff;
  --color-primary-500: var(--color-primary-default);
  --color-primary-600: color-mix(in srgb, var(--color-primary-default) 80%, black);
  
  /* Avoid: Redundant values */
  --color-primary-default: #0055ff;
  --color-primary-500: #0055ff; /* Same as default */
}
```

## Troubleshooting

### Common Issues

#### 1. Theme Not Applied

**Problem**: Components appear unstyled

**Solution**:
```css
/* Ensure proper import order */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';
/* Your overrides come after theme imports */
```

#### 2. Override Not Working

**Problem**: Custom tokens not taking effect

**Solution**:
```css
/* Check CSS specificity */
:host {
  /* This will work */
  --color-primary-default: #ff6600;
}

/* This might not work if specificity is too low */
.my-component {
  --color-primary-default: #ff6600;
}
```

#### 3. Inconsistent Theming

**Problem**: Some components use old theme values

**Solution**:
```css
/* Use !important sparingly and only when necessary */
:host {
  --color-primary-default: #ff6600 !important;
}

/* Or increase specificity */
:host:not(.other-class) {
  --color-primary-default: #ff6600;
}
```

## Next Steps

- **Explore [Component Documentation](./README.md)** for component-specific theming
- **Check [CSS Variables Reference](./css-variables.md)** for complete token list
- **Review [Usage Guide](./usage.md)** for implementation examples
- **See [Accessibility Guidelines](./accessibility.md)** for accessible theming practices