# Color Tokens Documentation

This document provides guidelines for using our standardized color system across the application.

## Color Palette Structure

Each color in our system has 10 shades, numbered from 0 to 9, where:
- 0 is the lightest shade
- 9 is the darkest shade
- 5-6 are the base/primary shades

## Brand Colors

### Brand Primary (Blue)

This is our main brand color, used for primary actions, links, and brand identity elements.

| Token | Hex | Usage |
|-------|-----|-------|
| `var(--mantine-color-brand-primary-0)` | `#EAF4FF` | Background on hover states |
| `var(--mantine-color-brand-primary-1)` | `#D5E9FF` | Background of informational elements |
| `var(--mantine-color-brand-primary-2)` | `#B0D3FF` | Secondary backgrounds |
| `var(--mantine-color-brand-primary-3)` | `#8BBDFF` | Borders, separators |
| `var(--mantine-color-brand-primary-4)` | `#66A7FF` | Hover states for interactive elements |
| `var(--mantine-color-brand-primary-5)` | `#4191FF` | Icons, secondary buttons |
| `var(--mantine-color-brand-primary-6)` | `#1C7BFF` | **Primary buttons, links, focus states** |
| `var(--mantine-color-brand-primary-7)` | `#0065F2` | Active/pressed states |
| `var(--mantine-color-brand-primary-8)` | `#0055CC` | Tertiary text |
| `var(--mantine-color-brand-primary-9)` | `#004099` | Text on light backgrounds |

### Brand Secondary

This complementary color is used for secondary UI elements and visual hierarchy.

| Token | Hex | Usage |
|-------|-----|-------|
| `var(--mantine-color-brand-secondary-0)` | `#F0F4F9` | Alternative background |
| `var(--mantine-color-brand-secondary-1)` | `#E1E9F4` | Secondary hover backgrounds |
| `var(--mantine-color-brand-secondary-2)` | `#C3D4E9` | Disabled backgrounds |
| `var(--mantine-color-brand-secondary-3)` | `#A5BFDE` | Borders, dividers |
| `var(--mantine-color-brand-secondary-4)` | `#87AAD3` | Non-primary icons |
| `var(--mantine-color-brand-secondary-5)` | `#6995C8` | Highlighted text |
| `var(--mantine-color-brand-secondary-6)` | `#4B80BD` | **Secondary buttons, links** |
| `var(--mantine-color-brand-secondary-7)` | `#2D6BB2` | Active/pressed states for secondary elements |
| `var(--mantine-color-brand-secondary-8)` | `#1F5A99` | Secondary text on light backgrounds |
| `var(--mantine-color-brand-secondary-9)` | `#114480` | Dark text on light backgrounds |

### Brand Accent

This color is used for accent elements, call-to-actions, and highlighting important UI elements.

| Token | Hex | Usage |
|-------|-----|-------|
| `var(--mantine-color-brand-accent-0)` | `#FFF0EA` | Highlight backgrounds |
| `var(--mantine-color-brand-accent-1)` | `#FFE1D5` | Notification backgrounds |
| `var(--mantine-color-brand-accent-2)` | `#FFC3AD` | Secondary accent backgrounds |
| `var(--mantine-color-brand-accent-3)` | `#FFA584` | Accent borders |
| `var(--mantine-color-brand-accent-4)` | `#FF875B` | Accent hover states |
| `var(--mantine-color-brand-accent-5)` | `#FF6932` | Secondary CTAs |
| `var(--mantine-color-brand-accent-6)` | `#FF4A09` | **Primary CTAs, important actions** |
| `var(--mantine-color-brand-accent-7)` | `#D93A00` | Active/pressed states for accent elements |
| `var(--mantine-color-brand-accent-8)` | `#B02F00` | Dark accent text on light backgrounds |
| `var(--mantine-color-brand-accent-9)` | `#882400` | Very dark accent, use sparingly |

### Brand Gray

This is our neutral color, used for text, backgrounds, borders, and non-emphasized UI elements.

| Token | Hex | Usage |
|-------|-----|-------|
| `var(--mantine-color-brand-gray-0)` | `#F8F9FA` | Page backgrounds, light mode |
| `var(--mantine-color-brand-gray-1)` | `#F1F3F5` | Card/element backgrounds |
| `var(--mantine-color-brand-gray-2)` | `#E9ECEF` | Alternative backgrounds, hover states |
| `var(--mantine-color-brand-gray-3)` | `#DEE2E6` | **Borders, dividers, separators** |
| `var(--mantine-color-brand-gray-4)` | `#CED4DA` | Disabled elements, secondary borders |
| `var(--mantine-color-brand-gray-5)` | `#ADB5BD` | **Placeholder text, disabled text** |
| `var(--mantine-color-brand-gray-6)` | `#868E96` | **Secondary text** |
| `var(--mantine-color-brand-gray-7)` | `#495057` | **Primary text** |
| `var(--mantine-color-brand-gray-8)` | `#343A40` | Headings, emphasized text |
| `var(--mantine-color-brand-gray-9)` | `#212529` | Extra dark text, header text |

## Semantic Colors

### Success

Used for positive actions, success messages, and confirmations.

| Token | Hex | Usage |
|-------|-----|-------|
| `var(--mantine-color-success-0)` | `#EAFAF1` | Success background |
| `var(--mantine-color-success-1)` | `#D5F5E3` | Light success background |
| `var(--mantine-color-success-2)` | `#ABEBC6` | Secondary success background |
| `var(--mantine-color-success-3)` | `#82E0AA` | Success borders |
| `var(--mantine-color-success-4)` | `#58D68D` | Success hover states |
| `var(--mantine-color-success-5)` | `#2ECC71` | Secondary success elements |
| `var(--mantine-color-success-6)` | `#27AE60` | **Primary success elements, icons** |
| `var(--mantine-color-success-7)` | `#229954` | Active/pressed states |
| `var(--mantine-color-success-8)` | `#1E8449` | Dark success text |
| `var(--mantine-color-success-9)` | `#196F3D` | Very dark success, use sparingly |

### Warning

Used for warnings, alerts that need attention but aren't critical.

| Token | Hex | Usage |
|-------|-----|-------|
| `var(--mantine-color-warning-0)` | `#FEF9E7` | Warning background |
| `var(--mantine-color-warning-1)` | `#FCF3CF` | Light warning background |
| `var(--mantine-color-warning-2)` | `#F9E79F` | Secondary warning background |
| `var(--mantine-color-warning-3)` | `#F7DC6F` | Warning borders |
| `var(--mantine-color-warning-4)` | `#F4D03F` | Warning hover states |
| `var(--mantine-color-warning-5)` | `#F1C40F` | Secondary warning elements |
| `var(--mantine-color-warning-6)` | `#D4AC0D` | **Primary warning elements, icons** |
| `var(--mantine-color-warning-7)` | `#B7950B` | Active/pressed states |
| `var(--mantine-color-warning-8)` | `#9A7D0A` | Dark warning text |
| `var(--mantine-color-warning-9)` | `#7D6608` | Very dark warning, use sparingly |

### Error

Used for errors, destructive actions, and critical alerts.

| Token | Hex | Usage |
|-------|-----|-------|
| `var(--mantine-color-error-0)` | `#FDEDEC` | Error background |
| `var(--mantine-color-error-1)` | `#FADBD8` | Light error background |
| `var(--mantine-color-error-2)` | `#F5B7B1` | Secondary error background |
| `var(--mantine-color-error-3)` | `#F1948A` | Error borders |
| `var(--mantine-color-error-4)` | `#EC7063` | Error hover states |
| `var(--mantine-color-error-5)` | `#E74C3C` | Secondary error elements |
| `var(--mantine-color-error-6)` | `#CB4335` | **Primary error elements, icons** |
| `var(--mantine-color-error-7)` | `#B03A2E` | Active/pressed states |
| `var(--mantine-color-error-8)` | `#943126` | Dark error text |
| `var(--mantine-color-error-9)` | `#78281F` | Very dark error, use sparingly |

## Semantic Tokens

For common UI elements, use these semantic tokens:

| Token | Maps to | Usage |
|-------|--------|-------|
| `var(--mantine-other-headerBgColor)` | `var(--mantine-color-body)` | Header background |
| `var(--mantine-other-headerBorderColor)` | `var(--mantine-color-brand-gray-3)` | Header borders |
| `var(--mantine-other-navigationActiveColor)` | `var(--mantine-color-brand-primary-6)` | Active navigation items |
| `var(--mantine-other-navigationHoverColor)` | `var(--mantine-color-brand-primary-0)` | Hover state for navigation |
| `var(--mantine-other-buttonPrimaryBg)` | `var(--mantine-color-brand-primary-6)` | Primary button background |
| `var(--mantine-other-buttonSecondaryBg)` | `var(--mantine-color-brand-secondary-6)` | Secondary button background |
| `var(--mantine-other-buttonAccentBg)` | `var(--mantine-color-brand-accent-6)` | Accent button background |

## Usage in CSS

### For direct CSS usage

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

### For light/dark mode support

```css
.my-element {
  color: light-dark(var(--mantine-color-brand-gray-7), var(--mantine-color-brand-gray-0));
  background-color: light-dark(var(--mantine-color-brand-gray-0), var(--mantine-color-brand-gray-8));
}
```

## Usage in Components (with Mantine)

```tsx
import { Button } from '@mantine/core';

// Using theme colors
<Button color="brand-primary">Primary Button</Button>
<Button color="brand-secondary">Secondary Button</Button>
<Button color="brand-accent">Accent Button</Button>

// Using specific shade
<Button color="brand-primary.6">Custom Shade Button</Button>
```