# Color System Migration Guide

This guide will help you migrate your components to use our new standardized color system.

## Why Migrate?

- **Consistency**: Ensure all UI elements have consistent colors
- **Maintainability**: Easier to update the design system
- **Accessibility**: Better contrast and readability
- **Dark Mode**: Simplified light/dark mode support

## Migration Steps

### 1. Identify Current Color Usage

First, identify all hardcoded colors or direct Mantine color variables in your component:

```css
/* Before */
.element {
  color: #333;
  background-color: var(--mantine-color-blue-6); 
  border: 1px solid var(--mantine-color-gray-3);
}
```

### 2. Replace with Theme Color Tokens

Replace hardcoded colors and direct Mantine variables with our standardized tokens:

```css
/* After */
.element {
  color: var(--mantine-color-brand-gray-7);
  background-color: var(--mantine-color-brand-primary-6);
  border: 1px solid var(--mantine-color-brand-gray-3);
}
```

### 3. Use Semantic Color Tokens Where Available

For common UI elements, use semantic tokens:

```css
/* Before */
.header {
  background-color: var(--mantine-color-body);
  border-bottom: 1px solid var(--mantine-color-gray-3);
}

/* After */
.header {
  background-color: var(--mantine-other-headerBgColor);
  border-bottom: 1px solid var(--mantine-other-headerBorderColor);
}
```

### 4. Use Light/Dark Mode Consistently

For elements that need different colors in light/dark mode:

```css
/* Before */
.text {
  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-0));
}

/* After */
.text {
  color: light-dark(var(--mantine-color-brand-gray-7), var(--mantine-color-brand-gray-0));
}
```

### 5. Update Inline Styles in Components

For inline styles in components:

```tsx
// Before
<Box style={{ color: theme.colors.blue[6] }} />

// After
<Box style={{ color: 'var(--mantine-color-brand-primary-6)' }} />

// Or better, use Mantine props
<Box c="brand-primary.6" />
```

## Mapping Old Colors to New Colors

Use this reference to map old color values to our new color system:

| Old Color | New Color |
|-----------|-----------|
| `var(--mantine-color-blue-0)` | `var(--mantine-color-brand-primary-0)` |
| `var(--mantine-color-blue-1)` | `var(--mantine-color-brand-primary-1)` |
| `var(--mantine-color-blue-4)` | `var(--mantine-color-brand-primary-4)` |
| `var(--mantine-color-blue-6)` | `var(--mantine-color-brand-primary-6)` |
| `var(--mantine-color-blue-7)` | `var(--mantine-color-brand-primary-7)` |
| `var(--mantine-color-blue-filled)` | `var(--mantine-other-navigationActiveColor)` |
| `var(--mantine-color-gray-0)` | `var(--mantine-color-brand-gray-0)` |
| `var(--mantine-color-gray-3)` | `var(--mantine-color-brand-gray-3)` |
| `var(--mantine-color-gray-4)` | `var(--mantine-color-brand-gray-4)` |
| `var(--mantine-color-gray-5)` | `var(--mantine-color-brand-gray-5)` |
| `var(--mantine-color-gray-7)` | `var(--mantine-color-brand-gray-7)` |
| `var(--mantine-color-dark-0)` | `var(--mantine-color-brand-gray-0)` |
| `var(--mantine-color-dark-4)` | `var(--mantine-color-brand-gray-4)` |
| `var(--mantine-color-dark-6)` | `var(--mantine-color-brand-gray-6)` |
| `var(--mantine-color-dark-8)` | `var(--mantine-color-brand-gray-8)` |

## Examples

### Header Component Example

```css
/* Before */
.header {
  background-color: var(--mantine-color-body);
  border-bottom: 1px solid light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-4));
}

.link {
  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-0));
}

.link:hover {
  background-color: light-dark(var(--mantine-color-gray-0), var(--mantine-color-dark-6));
}

.active {
  background-color: var(--mantine-color-blue-filled);
  color: var(--mantine-color-white);
}

/* After */
.header {
  background-color: var(--mantine-other-headerBgColor);
  border-bottom: 1px solid var(--mantine-other-headerBorderColor);
}

.link {
  color: light-dark(var(--mantine-color-brand-gray-7), var(--mantine-color-brand-gray-0));
}

.link:hover {
  background-color: light-dark(var(--mantine-color-brand-gray-1), var(--mantine-color-brand-gray-8));
}

.active {
  background-color: var(--mantine-other-navigationActiveColor);
  color: var(--mantine-color-white);
}
```

### Button Component Example

```tsx
// Before
<Button 
  style={{ 
    backgroundColor: theme.colors.blue[6],
    color: 'white'
  }}
>
  Click me
</Button>

// After
<Button color="brand-primary">Click me</Button>
```

## Testing Your Migration

After migrating, run stylelint to ensure you're not using hardcoded colors:

```bash
yarn stylelint
```

## Need Help?

Refer to the `color-tokens.md` file or the `ColorPalette` component in Storybook for a complete reference of our color system.