0
# PostCSS Colormin
1

2
PostCSS Colormin is a PostCSS plugin that automatically minifies color values in CSS files by converting them to their shortest possible representation. It intelligently transforms color formats (RGB, HSL, hex, named colors) based on browser compatibility, optimizing file size while maintaining visual accuracy.
3

4
## Package Information
5

6
- **Package Name**: postcss-colormin
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install postcss-colormin`
10

11
## Core Imports
12

13
```javascript
14
const colormin = require("postcss-colormin");
15
```
16

17
For standalone color minification:
18

19
```javascript
20
const minifyColor = require("postcss-colormin/src/minifyColor");
21
```
22

23
For TypeScript:
24

25
```typescript
26
import colormin from "postcss-colormin";
27
import minifyColor from "postcss-colormin/src/minifyColor";
28
```
29

30
## Basic Usage
31

32
```javascript
33
const postcss = require("postcss");
34
const colormin = require("postcss-colormin");
35

36
const css = 'h1 {color: rgba(255, 0, 0, 1)}';
37
const result = postcss([colormin()]).process(css).css;
38
console.log(result); // => 'h1 {color:red}'
39
```
40

41
With options:
42

43
```javascript
44
const result = postcss([
45
  colormin({
46
    alphaHex: true,
47
    transparent: false,
48
    name: true
49
  })
50
]).process(css);
51
```
52

53
## Architecture
54

55
PostCSS Colormin is built around several key components:
56

57
- **Plugin Creator**: Main function that creates PostCSS plugin instances with browser-aware optimizations
58
- **Color Transformer**: Core transformation engine that walks CSS value trees and minifies colors
59
- **Browser Integration**: Automatic browserslist integration for context-aware color format selection
60
- **Utility Function**: Standalone color minification function for programmatic use
61
- **Caching System**: Internal caching to optimize repeated transformations
62

63
## Capabilities
64

65
### PostCSS Plugin
66

67
Creates a PostCSS plugin for automatic color minification in CSS processing pipelines.
68

69
```typescript { .api }
70
/**
71
 * Creates a PostCSS plugin for color minification
72
 * @param config - Optional configuration object
73
 * @returns PostCSS plugin instance
74
 */
75
declare function pluginCreator(config?: Options): import("postcss").Plugin;
76

77
/**
78
 * Static property identifying this as a PostCSS plugin
79
 */
80
pluginCreator.postcss: true;
81

82
// CommonJS export structure
83
export = pluginCreator;
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
const postcss = require("postcss");
90
const colormin = require("postcss-colormin");
91

92
// Basic usage
93
const result = await postcss([colormin()])
94
  .process('h1 { color: rgba(255, 0, 0, 1) }');
95
// Output: 'h1 { color: red }'
96

97
// With custom browserslist
98
const result = await postcss([
99
  colormin({
100
    overrideBrowserslist: ['Chrome >= 62']
101
  })
102
]).process('h1 { color: hsla(0, 100%, 50%, 0.4) }');
103
// Output: 'h1 { color: #f006 }' (using 4-digit hex)
104

105
// Disable specific optimizations
106
const result = await postcss([
107
  colormin({
108
    transparent: false,  // Don't convert rgba(0,0,0,0) to transparent
109
    name: false          // Don't convert hex to named colors
110
  })
111
]).process('h1 { color: #ff0000; background: rgba(0,0,0,0) }');
112
```
113

114
### Standalone Color Minification
115

116
Minifies individual color values without PostCSS processing.
117

118
```typescript { .api }
119
/**
120
 * Performs color value minification
121
 * @param input - CSS color value string
122
 * @param options - Minification options
123
 * @returns Minified color value string
124
 */
125
declare function minifyColor(input: string, options?: MinifyColorOptions): string;
126

127
// CommonJS export structure
128
export = minifyColor;
129
```
130

131
**Usage Examples:**
132

133
```javascript
134
const minifyColor = require("postcss-colormin/src/minifyColor");
135

136
// Basic color minification
137
minifyColor("rgba(255, 0, 0, 1)"); // => "red"
138
minifyColor("#ffffff"); // => "#fff"
139
minifyColor("hsl(0, 100%, 50%)"); // => "red"
140

141
// With options
142
minifyColor("rgba(255, 0, 0, 0.5)", { 
143
  alphaHex: true 
144
}); // => "#ff0080"
145

146
// Invalid colors pass through
147
minifyColor("not-a-color"); // => "not-a-color"
148
minifyColor("rgb(50%, 23, 54)"); // => "rgb(50%, 23, 54)"
149
```
150

151
## Configuration Options
152

153
### MinifyColorOptions
154

155
Color minification behavior configuration.
156

157
```typescript { .api }
158
interface MinifyColorOptions {
159
  /** Enable hex color optimization (default: true) */
160
  hex?: boolean;
161
  /** Enable 4/8-digit hex with alpha channel (default: false, browser-dependent) */
162
  alphaHex?: boolean;
163
  /** Enable RGB format optimization (default: true) */
164
  rgb?: boolean;
165
  /** Enable HSL format optimization (default: true) */
166
  hsl?: boolean;
167
  /** Enable named color optimization (default: true) */
168
  name?: boolean;
169
  /** Enable transparent keyword optimization (default: true, browser-dependent) */
170
  transparent?: boolean;
171
}
172
```
173

174
### Browser Configuration Options
175

176
Browserslist integration for browser-aware optimizations.
177

178
```typescript { .api }
179
interface AutoprefixerOptions {
180
  /** Override browserslist configuration */
181
  overrideBrowserslist?: string | string[];
182
}
183

184
interface BrowserslistOptions {
185
  /** Custom usage statistics for browserslist */
186
  stats?: any;
187
  /** Path for browserslist config file resolution */
188
  path?: string;
189
  /** Environment for browserslist (e.g., 'production', 'development') */
190
  env?: string;
191
}
192
```
193

194
### Complete Options Type
195

196
```typescript { .api }
197
type Options = MinifyColorOptions & AutoprefixerOptions & BrowserslistOptions;
198
```
199

200
## Color Transformation Examples
201

202
### Format Conversions
203

204
```javascript
205
// Hex to named colors
206
minifyColor("#ff0000"); // => "red"
207
minifyColor("#00ff00"); // => "#0f0" (shorter than "lime")
208

209
// RGB/RGBA to optimal format  
210
minifyColor("rgb(255, 0, 0)"); // => "red"
211
minifyColor("rgba(255, 0, 0, 0.5)"); // => "rgba(255,0,0,.5)"
212
minifyColor("rgba(255, 0, 0, 1)"); // => "red"
213

214
// HSL/HSLA to optimal format
215
minifyColor("hsl(0, 100%, 50%)"); // => "red" 
216
minifyColor("hsla(0, 100%, 50%, 0.5)"); // => "rgba(255,0,0,.5)"
217

218
// Transparent handling
219
minifyColor("rgba(0, 0, 0, 0)"); // => "transparent"
220
minifyColor("hsla(0, 0%, 0%, 0)"); // => "transparent"
221
```
222

223
### Case Handling
224

225
```javascript
226
// Case normalization
227
minifyColor("RED"); // => "red"
228
minifyColor("#FFFFFF"); // => "#fff"
229
minifyColor("RGB(255, 0, 0)"); // => "red"
230
```
231

232
### Browser-Specific Optimizations
233

234
```javascript
235
// Modern browsers with alphaHex support
236
const modernOptions = { alphaHex: true };
237
minifyColor("rgba(255, 0, 0, 0.4)", modernOptions); // => "#f006"
238

239
// Legacy browser compatibility  
240
const legacyOptions = { transparent: false };
241
minifyColor("rgba(0, 0, 0, 0)", legacyOptions); // => "rgba(0,0,0,0)"
242
```
243

244
## CSS Processing Behavior
245

246
### Properties Processed
247

248
The plugin processes color values in most CSS properties but excludes certain properties where colors should not be modified:
249

250
- **Processed**: `color`, `background`, `border-color`, `box-shadow`, etc.
251
- **Excluded**: `font`, `font-family`, `src`, `filter`, `-webkit-tap-highlight-color`, `composes`
252

253
### Value Types Handled
254

255
```css
256
/* Supported color formats */
257
.example {
258
  /* Named colors */
259
  color: red; /* => red (unchanged) */
260
  color: yellow; /* => #ff0 */
261
  
262
  /* Hex colors */
263
  background: #ffffff; /* => #fff */
264
  border: #f00; /* => red */
265
  
266
  /* RGB/RGBA functions */
267
  box-shadow: rgb(255, 255, 255); /* => #fff */
268
  color: rgba(255, 0, 0, 0.5); /* => rgba(255,0,0,.5) */
269
  
270
  /* HSL/HSLA functions */
271
  background: hsl(0, 100%, 50%); /* => red */
272
  color: hsla(134, 50%, 50%, 1); /* => #40bf5e */
273
  
274
  /* Complex values with multiple colors */
275
  background: linear-gradient(#ff0000, yellow); /* => linear-gradient(red, #ff0) */
276
}
277

278
/* Values that are NOT processed */
279
.excluded {
280
  font-family: black; /* Unchanged - font names */
281
  filter: sepia(100%); /* Unchanged - filter functions */
282
  content: "red"; /* Unchanged - string content */
283
}
284
```
285

286
### Math Function Handling
287

288
```css
289
/* CSS math functions are excluded from color processing */
290
.math {
291
  width: calc(100vw / 2 - 6px + 0); /* Unchanged */
292
  height: min(100vh, 500px); /* Unchanged */
293
}
294
```