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:

/* 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:

/* 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:

/* 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:

/* 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:

// 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

/* 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

// 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:

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.

4.6 KiB Raw Blame History