or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

browser-global.md browser-polyfill.md index.md postcss-plugin.md

tile.json

PostCSS Plugin

The PostCSS plugin transforms prefers-color-scheme media queries into cross-browser compatible color media queries during the build process, enabling support for legacy browsers that don't natively support the CSS Media Queries Level 5 specification.

Capabilities

Plugin Creator Function

Main export that creates a PostCSS plugin instance with optional configuration.

/**
 * Creates a PostCSS plugin for transforming prefers-color-scheme queries
 * @param opts - Optional plugin configuration
 * @returns PostCSS plugin instance
 */
declare const prefersColorScheme: PluginCreator<pluginOptions>;

The plugin creator function has a postcss property set to true for PostCSS plugin identification.

Plugin Options

Configuration options for customizing plugin behavior.

/**
 * Configuration options for the PostCSS plugin
 */
interface pluginOptions {
  /** 
   * Preserve the original notation alongside transformed queries
   * @default true
   */
  preserve?: boolean;
}

Usage Examples:

import prefersColorScheme from 'css-prefers-color-scheme';
import postcss from 'postcss';

// Default behavior (preserve: true)
const plugin1 = prefersColorScheme();

// Disable preservation of original queries
const plugin2 = prefersColorScheme({ preserve: false });

// Use with PostCSS
const result = await postcss([
  prefersColorScheme({ preserve: true })
]).process(css, { from: undefined });

Transformation Behavior

The plugin performs the following transformations:

With preserve: true (default):

/* Input */
@media (prefers-color-scheme: dark) {
  :root { --bg: #000; }
}

/* Output */
@media (color: 48842621) {
  :root { --bg: #000; }
}

@media (prefers-color-scheme: dark) {
  :root { --bg: #000; }
}

With preserve: false:

/* Input */
@media (prefers-color-scheme: dark) {
  :root { --bg: #000; }
}

/* Output */
@media (color: 48842621) {
  :root { --bg: #000; }
}

Color Values

The plugin uses specific color values to represent different color schemes:

Dark scheme: (color: 48842621)
Light scheme: (color: 70318723)

These values are recognized by the browser polyfill to activate the appropriate color scheme.

PostCSS Integration

Basic PostCSS usage:

const postcss = require('postcss');
const prefersColorScheme = require('css-prefers-color-scheme');

postcss([
  prefersColorScheme()
]).process(css, { from: undefined })
  .then(result => {
    console.log(result.css);
  });

With other PostCSS plugins:

const postcss = require('postcss');
const prefersColorScheme = require('css-prefers-color-scheme');
const autoprefixer = require('autoprefixer');

postcss([
  prefersColorScheme(),
  autoprefixer()
]).process(css, { from: undefined });

Webpack configuration:

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  ['css-prefers-color-scheme', { preserve: true }]
                ]
              }
            }
          }
        ]
      }
    ]
  }
};

Regular Expression Pattern

The plugin uses a regular expression to match prefers-color-scheme declarations:

const prefersInterfaceRegExp = /\(\s*prefers-color-scheme\s*:\s*(dark|light)\s*\)/gi;

This pattern matches:

(prefers-color-scheme: dark)
(prefers-color-scheme: light)
Variations with whitespace