postcss-color-scheme

postcss-color-scheme

Table of Contents

• postcss-color-scheme
  • Table of Contents
  • Changelog
  • Installation
  • Design Decisions
  • Supported At Rules
  • Global Variant
  • Test Cases & Examples
  • Tailwind Support

Changelog

Postcss plugin for handling prefers-color-scheme, plus tailwind support

Input

.my-class {
  color: black;
  @dark {
    color: white;
  }
}

Output

.my-class {
  color: black;
}

html[data-color-scheme="dark"] .my-class {
  color: white;
}

@media (prefers-color-scheme: dark) {
  html:not([data-color-scheme="light"]) .my-class {
    color: white;
  }
}

Installation

npm install --save-dev postcss postcss-color-scheme

Add to your postcss config

module.exports = {
  plugins: [
+   require('postcss-color-scheme'),
  ],
};

Design Decisions

You might have noticed a couple of opinionated code at the top of this document. These are extracted from my work, and currently serve my use cases very well. Should you have concerns, suggestions for improvements, or solution for making this more generic, feel free to open an issue. Thanks!

1. Rely on data-color-scheme for explicit theme settings. This requires setting data-color-scheme on the root html element.

2. Provide fallback to when user has not explicitly select a theme. Let's refer to the demo above, with rules enumerated:

     /* (1) */
     .my-class {
       color: black;
     }
   
     /* (2) */
     html[data-color-scheme="dark"] .my-class {
       color: white;
     }
   
     /* (3) */
     @media (prefers-color-scheme: dark) {
       html:not([data-color-scheme="light"]) .my-class {
         color: white;
       }
     }
   

   Imagine your system provides 3 options: dark, light, and system (default). There are 4 possible scenarios.

   1. User has not explicitly selected a theme (theme = system), and the system prefers light (prefers-color-scheme = light):

      --> (1) applies.

   2. User has not explicitly selected a theme (theme = system), and the system prefers dark (prefers-color-scheme = dark):

      --> (1) & (3) applies, (3) takes precedence because of its higher specificity.

   3. User selected dark (data-color-theme set to dark on root html) :

      --> (1) & (2) applies, (2) takes precedence because of its higher specificity.

   4. User selected light (data-color-theme set to light on root html) :

      --> (1) applies.

Supported At Rules

At Rule	Description
@dark	apply rules for dark color scheme
@light	apply rules for light color scheme

Global Variant

postcss-color-scheme supports the :global syntax, often seen in css modules and similar systems.

Input

.my-class {
  @dark global {
    color: white;
  }
}

:global(html[data-color-scheme="dark"]) .my-class {
  color: white;
}
@media (prefers-color-scheme: dark) {
  :global(html:not([data-color-scheme="light"])) .my-class {
    color: white;
  }
}

Test Cases & Examples

The following table lists test cases covered by this plugin, please refer to tests for details and to test input css as examples

Test Case	Description	Input	Output
nest in other media queries	@media (min-width: 768px) { .my-class { @dark { color: white } } }	input	output
with combined selector	.my-class, .others { @dark { color: white } }	input	output
with postcss-nesting	.my-class { & .nested { @dark { color: white } } }	input	output
with postcss-nested	.my-class { .nested { @dark { color: white } } }	input	output

Tailwind Support

Make sure you have installed and configured tailwindcss.

npm install --save-dev tailwindcss

Add postcss-color-scheme to your tailwind config as a plugin, and turn off the default darkMode handling.

/** @type {import("tailwindcss").Config } */
module.exports = {
  // your config ...
  darkMode: '',
  plugins: [require('postcss-color-scheme/lib/tailwind')],
};

Now, the following is available:

<input class="text-white dark:text-black light:border-gray-500">