0
# PostCSS Color Function
1

2
PostCSS Color Function is a PostCSS plugin that transforms W3C CSS Color Module Level 4 color() functions to more compatible CSS syntax. It processes CSS declarations containing color() functions and converts them to standard CSS color values like rgba() or hex, enabling developers to use modern CSS color syntax while maintaining browser compatibility.
3

4
## Deprecation Notice
5

6
**⚠️ Important**: This package is deprecated as the `color()` function was changed to `color-mod()` and later removed entirely from the CSS Color Module Level 4 specification. For modern color manipulation, consider using [postcss-color-mod-function](https://github.com/jonathantneal/postcss-color-mod-function) or other CSS color transformation tools.
7

8
## Package Information
9

10
- **Package Name**: postcss-color-function  
11
- **Package Type**: npm
12
- **Language**: JavaScript (ES5/CommonJS)
13
- **Installation**: `npm install postcss-color-function`
14

15
## Core Imports
16

17
```javascript
18
const colorFunction = require("postcss-color-function");
19
```
20

21
## Basic Usage
22

23
```javascript
24
const postcss = require("postcss");
25
const colorFunction = require("postcss-color-function");
26

27
// Process CSS with default options
28
const result = postcss()
29
  .use(colorFunction())
30
  .process(css);
31

32
// Process CSS with custom options
33
const result = postcss()
34
  .use(colorFunction({
35
    preserveCustomProps: false  // Remove declarations with CSS custom properties
36
  }))
37
  .process(css);
38
```
39

40
Input CSS:
41
```css
42
body {
43
  background: color(red a(90%));
44
  color: color(hsla(125, 50%, 50%, .4) hue(200));
45
  border: color(red tint(50%));
46
}
47
```
48

49
Output CSS:
50
```css
51
body {
52
  background: rgba(255, 0, 0, 0.9);
53
  color: rgba(64, 149, 191, 0.4);
54
  border: rgb(255, 128, 128);
55
}
56
```
57

58
## Capabilities
59

60
### Plugin Factory Function
61

62
Creates a PostCSS plugin instance that transforms color() functions to compatible CSS.
63

64
```javascript { .api }
65
/**
66
 * Creates a PostCSS plugin that transforms color() functions
67
 * @param {PluginOptions} options - Configuration options
68
 * @returns {PostCSS.Plugin} PostCSS plugin function
69
 */
70
function postcssColorFunction(options?: PluginOptions): PostCSS.Plugin;
71

72
interface PluginOptions {
73
  /** Whether to preserve declarations containing CSS custom properties (var()). Default: true */
74
  preserveCustomProps?: boolean;
75
}
76
```
77

78
**Plugin Behavior:**
79
- Processes all CSS declarations in the stylesheet
80
- Only transforms declarations containing `color(` functions
81
- Skips declarations with CSS custom properties (var()) when `preserveCustomProps: true`
82
- Removes declarations with CSS custom properties when `preserveCustomProps: false`
83
- Emits PostCSS messages for skipped declarations
84
- Provides detailed error messages for parsing failures
85

86
### Supported Color Adjusters
87

88
The plugin supports the complete CSS Color Module Level 4 color() function syntax with all standard color adjusters:
89

90
#### RGB Channel Adjusters
91
```css
92
/* Adjust individual color channels */
93
color(red red(+20))        /* Add to red channel */
94
color(red green(-10%))     /* Subtract from green channel */
95
color(red blue(*1.5))      /* Multiply blue channel */
96
color(red alpha(0.8))      /* Set alpha channel */
97
color(red a(0.8))          /* Shorthand for alpha */
98
```
99

100
#### HSL Adjusters
101
```css
102
/* Adjust hue, saturation, lightness */
103
color(red hue(+45deg))           /* Adjust hue */
104
color(red h(+45deg))             /* Shorthand for hue */
105
color(red saturation(+20%))      /* Adjust saturation */
106
color(red s(+20%))               /* Shorthand for saturation */
107
color(red lightness(-10%))       /* Adjust lightness */
108
color(red l(-10%))               /* Shorthand for lightness */
109
```
110

111
#### HWB Adjusters
112
```css
113
/* Adjust whiteness and blackness */
114
color(red whiteness(+20%))       /* Increase whiteness */
115
color(red w(+20%))               /* Shorthand for whiteness */
116
color(red blackness(-10%))       /* Decrease blackness */
117
color(red b(-10%))               /* Shorthand for blackness */
118
```
119

120
#### Advanced Color Functions
121
```css
122
/* Advanced color manipulation */
123
color(red tint(50%))                          /* Mix with white */
124
color(red shade(25%))                         /* Mix with black */
125
color(red blend(blue 30%))                    /* Blend with another color */
126
color(red blend(blue 30% hsl))                /* Blend in HSL color space */
127
color(red contrast(75%))                      /* Adjust contrast */
128
```
129

130
### Error Handling
131

132
The plugin provides comprehensive error handling:
133

134
**Parse Errors:**
135
- Invalid color values trigger PostCSS warnings
136
- Error messages include source location and problematic value
137
- Processing continues for other declarations
138

139
**Custom Property Handling:**
140
- `preserveCustomProps: true` (default): Skips processing, emits informational messages
141
- `preserveCustomProps: false`: Removes declarations entirely
142

143
**Message Types:**
144
- `skipped-color-function-with-custom-property`: When color() contains var() and is skipped
145
- Standard PostCSS warnings for parsing errors
146

147
### Complete Usage Example
148

149
```javascript
150
const fs = require("fs");
151
const postcss = require("postcss");
152
const colorFunction = require("postcss-color-function");
153

154
// Read input CSS
155
const css = fs.readFileSync("input.css", "utf8");
156

157
// Process with plugin
158
const result = postcss()
159
  .use(colorFunction({
160
    preserveCustomProps: true  // Default behavior
161
  }))
162
  .process(css);
163

164
// Handle messages
165
result.messages.forEach(message => {
166
  if (message.type === "skipped-color-function-with-custom-property") {
167
    console.log(`Skipped: ${message.word}`);
168
  }
169
});
170

171
// Get transformed CSS
172
const output = result.css;
173
```
174

175
## Types
176

177
```javascript { .api }
178
interface PluginOptions {
179
  /** 
180
   * Whether to preserve declarations containing CSS custom properties (var()).
181
   * When true (default): Skips processing and emits informational messages
182
   * When false: Removes declarations containing var() entirely
183
   */
184
  preserveCustomProps?: boolean;
185
}
186

187
interface PostCSS.Plugin {
188
  /** PostCSS plugin processor function */
189
  (root: PostCSS.Root, result: PostCSS.Result): void;
190
}
191

192
interface PostCSS.Message {
193
  /** Plugin name that generated the message */
194
  plugin: string;
195
  /** Message type identifier */
196
  type: string;
197
  /** The problematic CSS value */
198
  word: string;
199
  /** Human-readable message description */
200
  message: string;
201
}
202
```