0
# Color Functions
1

2
Comprehensive color manipulation and analysis functions supporting HSL, RGB, HEX, and named colors with automatic format detection and intelligent color theory operations.
3

4
## Capabilities
5

6
### Color Adjustment Functions
7

8
Functions for adjusting color properties while maintaining color format consistency.
9

10
```javascript { .api }
11
/**
12
 * Increases the lightness of a color by a specified amount
13
 * @param amount - Float between 0 and 1 representing the amount to lighten
14
 * @param color - Color string in any supported format
15
 * @returns Lightened color in same format as input
16
 */
17
function lighten(amount: number, color: string): string;
18

19
/**
20
 * Decreases the lightness of a color by a specified amount
21
 * @param amount - Float between 0 and 1 representing the amount to darken
22
 * @param color - Color string in any supported format
23
 * @returns Darkened color in same format as input
24
 */
25
function darken(amount: number, color: string): string;
26

27
/**
28
 * Increases the saturation of a color by a specified amount
29
 * @param amount - Float between 0 and 1 representing the amount to saturate
30
 * @param color - Color string in any supported format
31
 * @returns More saturated color in same format as input
32
 */
33
function saturate(amount: number, color: string): string;
34

35
/**
36
 * Decreases the saturation of a color by a specified amount
37
 * @param amount - Float between 0 and 1 representing the amount to desaturate
38
 * @param color - Color string in any supported format
39
 * @returns Less saturated color in same format as input
40
 */
41
function desaturate(amount: number, color: string): string;
42

43
/**
44
 * Adjusts the hue of a color by a specified number of degrees
45
 * @param degree - Number of degrees to adjust hue (-360 to 360)
46
 * @param color - Color string in any supported format
47
 * @returns Color with adjusted hue in same format as input
48
 */
49
function adjustHue(degree: number, color: string): string;
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
import { lighten, darken, saturate, desaturate, adjustHue } from "polished";
56

57
const baseColor = "#3498db";
58

59
// Lightness adjustments
60
const lighter = lighten(0.2, baseColor);  // "#5DADE2"
61
const darker = darken(0.15, baseColor);   // "#2E86C1"
62

63
// Saturation adjustments
64
const vibrant = saturate(0.3, baseColor);     // More vivid
65
const muted = desaturate(0.2, baseColor);     // More gray
66

67
// Hue rotation
68
const warmer = adjustHue(30, baseColor);      // More towards purple
69
const cooler = adjustHue(-30, baseColor);     // More towards cyan
70
```
71

72
### Color Mixing and Blending
73

74
Functions for combining and blending colors with intelligent mixing algorithms.
75

76
```javascript { .api }
77
/**
78
 * Mixes two colors together by a specified weight
79
 * @param weight - Float between 0 and 1, weight of first color in the mix
80
 * @param color - First color string
81
 * @param otherColor - Second color string
82
 * @returns Mixed color as string
83
 */
84
function mix(weight: number, color: string, otherColor: string): string;
85

86
/**
87
 * Returns the complement color (opposite on color wheel)
88
 * @param color - Color string in any supported format
89
 * @returns Complement color in same format as input
90
 */
91
function complement(color: string): string;
92

93
/**
94
 * Inverts a color (RGB inversion)
95
 * @param color - Color string in any supported format
96
 * @returns Inverted color in same format as input
97
 */
98
function invert(color: string): string;
99

100
/**
101
 * Converts a color to grayscale
102
 * @param color - Color string in any supported format
103
 * @returns Grayscale equivalent in same format as input
104
 */
105
function grayscale(color: string): string;
106
```
107

108
### Opacity and Transparency
109

110
Functions for manipulating alpha channel and transparency.
111

112
```javascript { .api }
113
/**
114
 * Increases the opacity of a color
115
 * @param amount - Float between 0 and 1 representing the amount to increase opacity
116
 * @param color - Color string (supports alpha formats)
117
 * @returns Color with increased opacity
118
 */
119
function opacify(amount: number, color: string): string;
120

121
/**
122
 * Decreases the opacity of a color
123
 * @param amount - Float between 0 and 1 representing the amount to decrease opacity
124
 * @param color - Color string (supports alpha formats)
125
 * @returns Color with decreased opacity
126
 */
127
function transparentize(amount: number, color: string): string;
128
```
129

130
### Color Tinting and Shading
131

132
Functions for mixing colors with white (tint) or black (shade).
133

134
```javascript { .api }
135
/**
136
 * Mixes a color with white to create a tint
137
 * @param amount - Float between 0 and 1 representing the amount of white to mix
138
 * @param color - Color string in any supported format
139
 * @returns Tinted color (lighter version)
140
 */
141
function tint(amount: number, color: string): string;
142

143
/**
144
 * Mixes a color with black to create a shade
145
 * @param amount - Float between 0 and 1 representing the amount of black to mix
146
 * @param color - Color string in any supported format
147
 * @returns Shaded color (darker version)
148
 */
149
function shade(amount: number, color: string): string;
150
```
151

152
### Color Creation and Construction
153

154
Functions for creating colors from component values.
155

156
```javascript { .api }
157
/**
158
 * Creates an HSL color string
159
 * @param hue - Hue value (0-360)
160
 * @param saturation - Saturation as decimal (0-1)
161
 * @param lightness - Lightness as decimal (0-1)
162
 * @returns HSL color string
163
 */
164
function hsl(hue: number, saturation: number, lightness: number): string;
165

166
/**
167
 * Creates an HSLA color string with alpha
168
 * @param hue - Hue value (0-360)
169
 * @param saturation - Saturation as decimal (0-1)
170
 * @param lightness - Lightness as decimal (0-1)
171
 * @param alpha - Alpha as decimal (0-1)
172
 * @returns HSLA color string
173
 */
174
function hsla(hue: number, saturation: number, lightness: number, alpha: number): string;
175

176
/**
177
 * Creates an RGB color string
178
 * @param red - Red value (0-255)
179
 * @param green - Green value (0-255)
180
 * @param blue - Blue value (0-255)
181
 * @returns RGB color string
182
 */
183
function rgb(red: number, green: number, blue: number): string;
184

185
/**
186
 * Creates an RGBA color string with alpha
187
 * @param red - Red value (0-255)
188
 * @param green - Green value (0-255)
189
 * @param blue - Blue value (0-255)
190
 * @param alpha - Alpha as decimal (0-1)
191
 * @returns RGBA color string
192
 */
193
function rgba(red: number, green: number, blue: number, alpha: number): string;
194
```
195

196
### Color Analysis and Information
197

198
Functions for extracting information and analyzing color properties.
199

200
```javascript { .api }
201
/**
202
 * Gets the luminance value of a color
203
 * @param color - Color string in any supported format
204
 * @returns Luminance value as float (0-1)
205
 */
206
function getLuminance(color: string): number;
207

208
/**
209
 * Calculates the contrast ratio between two colors
210
 * @param color1 - First color string
211
 * @param color2 - Second color string
212
 * @returns Contrast ratio as float
213
 */
214
function getContrast(color1: string, color2: string): number;
215

216
/**
217
 * Checks if color combination meets WCAG contrast guidelines
218
 * @param color1 - First color string
219
 * @param color2 - Second color string
220
 * @returns Object with accessibility compliance information
221
 */
222
function meetsContrastGuidelines(color1: string, color2: string): ContrastScore;
223

224
/**
225
 * Returns the best contrasting color (black or white) for readability
226
 * @param color - Background color string
227
 * @param returnIfLightColor - Color to return if background is light (default: black)
228
 * @param returnIfDarkColor - Color to return if background is dark (default: white)
229
 * @returns Contrasting color for optimal readability
230
 */
231
function readableColor(
232
  color: string,
233
  returnIfLightColor?: string,
234
  returnIfDarkColor?: string
235
): string;
236
```
237

238
### Color Parsing and Conversion
239

240
Functions for parsing color strings and converting between formats.
241

242
```javascript { .api }
243
/**
244
 * Parses a color string and returns HSL values
245
 * @param color - Color string in any supported format
246
 * @returns Object with hue, saturation, lightness, and alpha properties
247
 */
248
function parseToHsl(color: string): HslColor;
249

250
/**
251
 * Parses a color string and returns RGB values
252
 * @param color - Color string in any supported format
253
 * @returns Object with red, green, blue, and alpha properties
254
 */
255
function parseToRgb(color: string): RgbColor;
256

257
/**
258
 * Converts HSL color object to color string
259
 * @param hslColor - HSL color object
260
 * @returns Color string representation
261
 */
262
function hslToColorString(hslColor: HslColor): string;
263

264
/**
265
 * Converts RGB color object to color string
266
 * @param rgbColor - RGB color object
267
 * @returns Color string representation
268
 */
269
function rgbToColorString(rgbColor: RgbColor): string;
270

271
/**
272
 * Converts a color to its optimal string representation
273
 * @param color - Color string or object
274
 * @returns Optimized color string (shortest valid format)
275
 */
276
function toColorString(color: string | RgbColor | HslColor): string;
277
```
278

279
### Color Property Setters
280

281
Functions for setting specific color channel values.
282

283
```javascript { .api }
284
/**
285
 * Sets the hue of a color to a specific value
286
 * @param hue - New hue value (0-360)
287
 * @param color - Color string in any supported format
288
 * @returns Color with new hue in same format as input
289
 */
290
function setHue(hue: number, color: string): string;
291

292
/**
293
 * Sets the lightness of a color to a specific value
294
 * @param lightness - New lightness value (0-1)
295
 * @param color - Color string in any supported format
296
 * @returns Color with new lightness in same format as input
297
 */
298
function setLightness(lightness: number, color: string): string;
299

300
/**
301
 * Sets the saturation of a color to a specific value
302
 * @param saturation - New saturation value (0-1)
303
 * @param color - Color string in any supported format
304
 * @returns Color with new saturation in same format as input
305
 */
306
function setSaturation(saturation: number, color: string): string;
307
```
308

309
## Types
310

311
```javascript { .api }
312
interface HslColor {
313
  hue: number;
314
  saturation: number;
315
  lightness: number;
316
  alpha?: number;
317
}
318

319
interface RgbColor {
320
  red: number;
321
  green: number;
322
  blue: number;
323
  alpha?: number;
324
}
325

326
interface ContrastScore {
327
  AA: boolean;
328
  AAA: boolean;
329
  AALarge: boolean;
330
  AAALarge: boolean;
331
}
332
```