or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-postcss-color-function

PostCSS plugin to transform W3C CSS color function to more compatible CSS.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/postcss-color-function@4.1.x

To install, run

npx @tessl/cli install tessl/npm-postcss-color-function@4.1.0

index.mddocs/

PostCSS Color Function

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.

Deprecation Notice

⚠️ 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 or other CSS color transformation tools.

Package Information

  • Package Name: postcss-color-function
  • Package Type: npm
  • Language: JavaScript (ES5/CommonJS)
  • Installation: npm install postcss-color-function

Core Imports

const colorFunction = require("postcss-color-function");

Basic Usage

const postcss = require("postcss");
const colorFunction = require("postcss-color-function");

// Process CSS with default options
const result = postcss()
  .use(colorFunction())
  .process(css);

// Process CSS with custom options
const result = postcss()
  .use(colorFunction({
    preserveCustomProps: false  // Remove declarations with CSS custom properties
  }))
  .process(css);

Input CSS:

body {
  background: color(red a(90%));
  color: color(hsla(125, 50%, 50%, .4) hue(200));
  border: color(red tint(50%));
}

Output CSS:

body {
  background: rgba(255, 0, 0, 0.9);
  color: rgba(64, 149, 191, 0.4);
  border: rgb(255, 128, 128);
}

Capabilities

Plugin Factory Function

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

/**
 * Creates a PostCSS plugin that transforms color() functions
 * @param {PluginOptions} options - Configuration options
 * @returns {PostCSS.Plugin} PostCSS plugin function
 */
function postcssColorFunction(options?: PluginOptions): PostCSS.Plugin;

interface PluginOptions {
  /** Whether to preserve declarations containing CSS custom properties (var()). Default: true */
  preserveCustomProps?: boolean;
}

Plugin Behavior:

  • Processes all CSS declarations in the stylesheet
  • Only transforms declarations containing color( functions
  • Skips declarations with CSS custom properties (var()) when preserveCustomProps: true
  • Removes declarations with CSS custom properties when preserveCustomProps: false
  • Emits PostCSS messages for skipped declarations
  • Provides detailed error messages for parsing failures

Supported Color Adjusters

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

RGB Channel Adjusters

/* Adjust individual color channels */
color(red red(+20))        /* Add to red channel */
color(red green(-10%))     /* Subtract from green channel */
color(red blue(*1.5))      /* Multiply blue channel */
color(red alpha(0.8))      /* Set alpha channel */
color(red a(0.8))          /* Shorthand for alpha */

HSL Adjusters

/* Adjust hue, saturation, lightness */
color(red hue(+45deg))           /* Adjust hue */
color(red h(+45deg))             /* Shorthand for hue */
color(red saturation(+20%))      /* Adjust saturation */
color(red s(+20%))               /* Shorthand for saturation */
color(red lightness(-10%))       /* Adjust lightness */
color(red l(-10%))               /* Shorthand for lightness */

HWB Adjusters

/* Adjust whiteness and blackness */
color(red whiteness(+20%))       /* Increase whiteness */
color(red w(+20%))               /* Shorthand for whiteness */
color(red blackness(-10%))       /* Decrease blackness */
color(red b(-10%))               /* Shorthand for blackness */

Advanced Color Functions

/* Advanced color manipulation */
color(red tint(50%))                          /* Mix with white */
color(red shade(25%))                         /* Mix with black */
color(red blend(blue 30%))                    /* Blend with another color */
color(red blend(blue 30% hsl))                /* Blend in HSL color space */
color(red contrast(75%))                      /* Adjust contrast */

Error Handling

The plugin provides comprehensive error handling:

Parse Errors:

  • Invalid color values trigger PostCSS warnings
  • Error messages include source location and problematic value
  • Processing continues for other declarations

Custom Property Handling:

  • preserveCustomProps: true (default): Skips processing, emits informational messages
  • preserveCustomProps: false: Removes declarations entirely

Message Types:

  • skipped-color-function-with-custom-property: When color() contains var() and is skipped
  • Standard PostCSS warnings for parsing errors

Complete Usage Example

const fs = require("fs");
const postcss = require("postcss");
const colorFunction = require("postcss-color-function");

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

// Process with plugin
const result = postcss()
  .use(colorFunction({
    preserveCustomProps: true  // Default behavior
  }))
  .process(css);

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

// Get transformed CSS
const output = result.css;

Types

interface PluginOptions {
  /** 
   * Whether to preserve declarations containing CSS custom properties (var()).
   * When true (default): Skips processing and emits informational messages
   * When false: Removes declarations containing var() entirely
   */
  preserveCustomProps?: boolean;
}

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

interface PostCSS.Message {
  /** Plugin name that generated the message */
  plugin: string;
  /** Message type identifier */
  type: string;
  /** The problematic CSS value */
  word: string;
  /** Human-readable message description */
  message: string;
}