0
# Color System
1

2
Material Design color palettes and color manipulation utilities.
3

4
## Color Palettes
5

6
Material UI provides 20 color palettes following Material Design specifications.
7

8
```typescript { .api }
9
/**
10
 * Material Design color palettes
11
 */
12
const colors: {
13
  common: CommonColors;
14
  red: ColorPalette;
15
  pink: ColorPalette;
16
  purple: ColorPalette;
17
  deepPurple: ColorPalette;
18
  indigo: ColorPalette;
19
  blue: ColorPalette;
20
  lightBlue: ColorPalette;
21
  cyan: ColorPalette;
22
  teal: ColorPalette;
23
  green: ColorPalette;
24
  lightGreen: ColorPalette;
25
  lime: ColorPalette;
26
  yellow: ColorPalette;
27
  amber: ColorPalette;
28
  orange: ColorPalette;
29
  deepOrange: ColorPalette;
30
  brown: ColorPalette;
31
  grey: ColorPalette;
32
  blueGrey: ColorPalette;
33
};
34

35
interface CommonColors {
36
  black: string;
37
  white: string;
38
}
39

40
interface ColorPalette {
41
  50: string;
42
  100: string;
43
  200: string;
44
  300: string;
45
  400: string;
46
  500: string;
47
  600: string;
48
  700: string;
49
  800: string;
50
  900: string;
51
  A100?: string; // Not available for brown, grey, blueGrey
52
  A200?: string;
53
  A400?: string;
54
  A700?: string;
55
}
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import { colors } from "@mui/material";
62
import { red, blue, green } from "@mui/material/colors";
63

64
// Using color palettes
65
const theme = createTheme({
66
  palette: {
67
    primary: {
68
      main: blue[500],
69
      light: blue[300],
70
      dark: blue[700],
71
    },
72
    secondary: {
73
      main: red[500],
74
    },
75
    error: {
76
      main: red[600],
77
    },
78
    success: {
79
      main: green[600],
80
    },
81
  },
82
});
83

84
// Direct color usage
85
<Box sx={{ bgcolor: colors.blue[100], color: colors.blue[900] }}>
86
  Blue themed content
87
</Box>
88

89
// Color variations
90
<Stack spacing={1}>
91
  <Box sx={{ bgcolor: red[50], p: 1 }}>Red 50 (lightest)</Box>
92
  <Box sx={{ bgcolor: red[100], p: 1 }}>Red 100</Box>
93
  <Box sx={{ bgcolor: red[500], p: 1, color: 'white' }}>Red 500 (main)</Box>
94
  <Box sx={{ bgcolor: red[900], p: 1, color: 'white' }}>Red 900 (darkest)</Box>
95
</Stack>
96
```
97

98
## Color Manipulation Functions
99

100
Utility functions for manipulating colors dynamically.
101

102
```typescript { .api }
103
/**
104
 * Adds alpha transparency to colors
105
 * @param color - Color string (hex, rgb, hsl, etc.)
106
 * @param value - Alpha value between 0 and 1
107
 * @returns Color string with alpha transparency
108
 */
109
function alpha(color: string, value: number): string;
110

111
/**
112
 * Darkens colors by mixing with black
113
 * @param color - Color string
114
 * @param coefficient - Darkening amount between 0 and 1
115
 * @returns Darkened color string
116
 */
117
function darken(color: string, coefficient: number): string;
118

119
/**
120
 * Lightens colors by mixing with white
121
 * @param color - Color string
122
 * @param coefficient - Lightening amount between 0 and 1
123
 * @returns Lightened color string
124
 */
125
function lighten(color: string, coefficient: number): string;
126

127
/**
128
 * Emphasizes colors (darkens light colors, lightens dark colors)
129
 * @param color - Color string
130
 * @param coefficient - Emphasis amount between 0 and 1
131
 * @returns Emphasized color string
132
 */
133
function emphasize(color: string, coefficient?: number): string;
134

135
/**
136
 * Calculates contrast ratio between two colors
137
 * @param foreground - Foreground color
138
 * @param background - Background color
139
 * @returns Contrast ratio (1-21, where 21 is maximum contrast)
140
 */
141
function getContrastRatio(foreground: string, background: string): number;
142

143
/**
144
 * Calculates relative luminance of a color
145
 * @param color - Color string
146
 * @returns Luminance value between 0 and 1
147
 */
148
function getLuminance(color: string): number;
149

150
/**
151
 * Converts hex color to RGB
152
 * @param hex - Hex color string (with or without #)
153
 * @returns RGB color string
154
 */
155
function hexToRgb(hex: string): string;
156

157
/**
158
 * Converts RGB color to hex
159
 * @param rgb - RGB color string
160
 * @returns Hex color string
161
 */
162
function rgbToHex(rgb: string): string;
163

164
/**
165
 * Converts HSL color to RGB
166
 * @param hsl - HSL color string
167
 * @returns RGB color string
168
 */
169
function hslToRgb(hsl: string): string;
170

171
/**
172
 * Decomposes color into its components
173
 * @param color - Color string
174
 * @returns Color object with type and values
175
 */
176
function decomposeColor(color: string): {
177
  type: string;
178
  values: number[];
179
  colorSpace?: string;
180
};
181

182
/**
183
 * Recomposes color from components
184
 * @param color - Color object
185
 * @returns Color string
186
 */
187
function recomposeColor(color: {
188
  type: string;
189
  values: number[];
190
  colorSpace?: string;
191
}): string;
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
import { 
198
  alpha, 
199
  darken, 
200
  lighten, 
201
  emphasize, 
202
  getContrastRatio,
203
  getLuminance 
204
} from "@mui/material/styles";
205
import { blue } from "@mui/material/colors";
206

207
// Color manipulation in styled components
208
const StyledButton = styled(Button)(({ theme }) => ({
209
  backgroundColor: theme.palette.primary.main,
210
  '&:hover': {
211
    backgroundColor: darken(theme.palette.primary.main, 0.1),
212
  },
213
  '&:active': {
214
    backgroundColor: darken(theme.palette.primary.main, 0.2),
215
  },
216
  boxShadow: `0 2px 8px ${alpha(theme.palette.primary.main, 0.3)}`,
217
}));
218

219
// Using in sx prop
220
<Box
221
  sx={{
222
    bgcolor: (theme) => alpha(theme.palette.primary.main, 0.1),
223
    border: (theme) => `1px solid ${lighten(theme.palette.primary.main, 0.5)}`,
224
    '&:hover': {
225
      bgcolor: (theme) => alpha(theme.palette.primary.main, 0.2),
226
    },
227
  }}
228
>
229
  Dynamically styled content
230
</Box>
231

232
// Contrast checking for accessibility
233
const textColor = getContrastRatio('#ffffff', blue[500]) > 4.5 ? '#ffffff' : '#000000';
234

235
// Luminance-based decisions
236
const backgroundColor = blue[500];
237
const textColor = getLuminance(backgroundColor) > 0.5 ? '#000000' : '#ffffff';
238
```
239

240
## Theme Color Configuration
241

242
```typescript { .api }
243
/**
244
 * Palette configuration interface
245
 */
246
interface PaletteOptions {
247
  mode?: 'light' | 'dark';
248
  primary?: PaletteColorOptions;
249
  secondary?: PaletteColorOptions;
250
  error?: PaletteColorOptions;
251
  warning?: PaletteColorOptions;
252
  info?: PaletteColorOptions;
253
  success?: PaletteColorOptions;
254
  grey?: Partial<ColorPalette>;
255
  common?: Partial<CommonColors>;
256
  text?: Partial<TypeText>;
257
  background?: Partial<TypeBackground>;
258
  action?: Partial<TypeAction>;
259
  divider?: string;
260
}
261

262
interface PaletteColorOptions {
263
  main: string;
264
  light?: string;
265
  dark?: string;
266
  contrastText?: string;
267
}
268

269
interface TypeText {
270
  primary: string;
271
  secondary: string;
272
  disabled: string;
273
}
274

275
interface TypeBackground {
276
  default: string;
277
  paper: string;
278
}
279

280
interface TypeAction {
281
  active: string;
282
  hover: string;
283
  hoverOpacity: number;
284
  selected: string;
285
  selectedOpacity: number;
286
  disabled: string;
287
  disabledBackground: string;
288
  disabledOpacity: number;
289
  focus: string;
290
  focusOpacity: number;
291
  activatedOpacity: number;
292
}
293
```
294

295
**Usage Examples:**
296

297
```typescript
298
import { createTheme } from "@mui/material/styles";
299
import { red, blue, green, orange, grey } from "@mui/material/colors";
300

301
// Custom color theme
302
const theme = createTheme({
303
  palette: {
304
    mode: 'light',
305
    primary: {
306
      main: blue[600],
307
      light: blue[400],
308
      dark: blue[800],
309
      contrastText: '#ffffff',
310
    },
311
    secondary: {
312
      main: orange[500],
313
      light: orange[300],
314
      dark: orange[700],
315
      contrastText: '#ffffff',
316
    },
317
    error: {
318
      main: red[600],
319
    },
320
    warning: {
321
      main: orange[800],
322
    },
323
    info: {
324
      main: blue[500],
325
    },
326
    success: {
327
      main: green[600],
328
    },
329
    grey: grey,
330
    text: {
331
      primary: 'rgba(0, 0, 0, 0.87)',
332
      secondary: 'rgba(0, 0, 0, 0.6)',
333
      disabled: 'rgba(0, 0, 0, 0.38)',
334
    },
335
    background: {
336
      default: '#fafafa',
337
      paper: '#ffffff',
338
    },
339
    divider: 'rgba(0, 0, 0, 0.12)',
340
  },
341
});
342

343
// Dark theme
344
const darkTheme = createTheme({
345
  palette: {
346
    mode: 'dark',
347
    primary: {
348
      main: blue[400],
349
    },
350
    secondary: {
351
      main: orange[400],
352
    },
353
    background: {
354
      default: '#121212',
355
      paper: '#1e1e1e',
356
    },
357
    text: {
358
      primary: '#ffffff',
359
      secondary: 'rgba(255, 255, 255, 0.7)',
360
    },
361
  },
362
});
363
```
364

365
## Color Usage Patterns
366

367
### Semantic Color System
368

369
```typescript
370
// Using semantic colors
371
<Alert severity="success">Success message</Alert>
372
<Alert severity="error">Error message</Alert>
373
<Alert severity="warning">Warning message</Alert>
374
<Alert severity="info">Info message</Alert>
375

376
// Corresponding theme colors
377
<Button color="primary">Primary Action</Button>
378
<Button color="secondary">Secondary Action</Button>
379
<Button color="error">Delete Action</Button>
380
<Button color="success">Confirm Action</Button>
381
```
382

383
### Accessibility-Conscious Color Usage
384

385
```typescript
386
import { getContrastRatio } from "@mui/material/styles";
387

388
function AccessibleColorPicker({ backgroundColor }: { backgroundColor: string }) {
389
  // Ensure sufficient contrast for text
390
  const textColor = getContrastRatio('#ffffff', backgroundColor) >= 4.5 
391
    ? '#ffffff' 
392
    : '#000000';
393
  
394
  return (
395
    <Box
396
      sx={{
397
        bgcolor: backgroundColor,
398
        color: textColor,
399
        p: 2,
400
        borderRadius: 1,
401
      }}
402
    >
403
      This text maintains WCAG AA contrast requirements
404
    </Box>
405
  );
406
}
407
```
408

409
### Dynamic Color Theming
410

411
```typescript
412
function DynamicThemedComponent() {
413
  const theme = useTheme();
414
  
415
  return (
416
    <Box
417
      sx={{
418
        // Base color from theme
419
        bgcolor: 'primary.main',
420
        // Manipulated variants
421
        borderTop: `4px solid ${darken(theme.palette.primary.main, 0.2)}`,
422
        borderBottom: `4px solid ${lighten(theme.palette.primary.main, 0.2)}`,
423
        // Semi-transparent overlay
424
        '&::before': {
425
          content: '""',
426
          position: 'absolute',
427
          top: 0,
428
          left: 0,
429
          right: 0,
430
          bottom: 0,
431
          backgroundColor: alpha(theme.palette.common.white, 0.1),
432
          pointerEvents: 'none',
433
        },
434
        // Hover state with emphasis
435
        '&:hover': {
436
          bgcolor: emphasize(theme.palette.primary.main, 0.1),
437
        },
438
      }}
439
    >
440
      Dynamically themed content
441
    </Box>
442
  );
443
}
444
```