https://github.com/calico32/postcss-color-contrast
PostCSS `color-contrast()` polyfill
https://github.com/calico32/postcss-color-contrast
color-contrast css polyfill postcss
Last synced: 3 months ago
JSON representation
PostCSS `color-contrast()` polyfill
- Host: GitHub
- URL: https://github.com/calico32/postcss-color-contrast
- Owner: calico32
- License: mit
- Created: 2022-08-10T15:35:24.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-08-30T21:54:19.000Z (almost 4 years ago)
- Last Synced: 2026-01-03T19:05:29.273Z (6 months ago)
- Topics: color-contrast, css, polyfill, postcss
- Language: TypeScript
- Homepage:
- Size: 1.19 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# postcss-color-contrast
This PostCSS plugin implements a polyfill for the `color-contrast()` function, part of the extremely new [CSS Color Module Level 6](https://drafts.csswg.org/css-color-6) spec.
Because the color is computed at compile-time, this plugin only supports literal colors (i.e. hex, `rgb()`, `hsl()`) and does not support `var()` or `calc()` expressions, `currentColor`, etc., and therefore must be placed near the end of the PostCSS chain.
No guarantees are made about the spec-compliance of this plugin, but I tried my best.
## TL;DR Spec behavior
### Syntax
```css
selector {
color: color-contrast( vs , [, ...] [to | AA | AA-large | AAA | AAA-large]);
}
```
I'll call the first color the "background", the list of colors the "foreground" colors, and the number/keyword the "target ratio".
### Semantics
**No target ratio: `color-contrast( vs , [, ...])`**
- The foreground color that has the highest contrast ratio with the background color is used.
**Target ratio: `color-contrast( vs , [, ...] to | AA | AA-large | AAA | AAA-large)`**
- The first foreground color in the list that has a contrast ratio greater than or equal to the target ratio is used.
- AA-large is the same as `3`.
- AA is the same as `4.5`.
- AAA-large is the same as `4.5`.
- AAA is the same as `7`.
## Usage
```sh
npm install --save-dev postcss-color-contrast
yarn add -D postcss-color-contrast
```
In your `postcss.config.js` file:
```js
module.exports = {
plugins: [
require('postcss-color-contrast'),
],
};
```
Or programmatically:
```js
const postcss = require('postcss')
postcss([
// ... other plugins here
require('postcss-color-contrast'),
// ... maybe more plugins here
]).process(css)
```
Additionally, use the `colorContrast()` function from JavaScript:
```js
import colorContrast from 'postcss-color-contrast/js'
const colorContrast = require('postcss-color-contrast/js')
// -> colorContrast(backgroundColor, foregroundColors, targetRatio, outputFormat)
// provide colors in any valid CSS color format, or a [r, g, b] array
colorContrast('#0f172a', ['#e5e5e5', '#171717']) // -> '#e5e5e5'
colorContrast('rgb(194, 65, 12)', ['hsl(0, 0%, 90%)', [23, 23, 23]], 'aa') // -> '#ffffff'
// provide an output format (defaults to 'hex')
const bg = '#6ee7b7'
const fg = ['#ecfdf5', '#d1fae5', '#a7f3d0', '#6ee7b7', '#34d399', '#10b981', '#059669', '#047857', '#065f46', '#064e3b']
const target = 'aa'
colorContrast(bg, fg, target) // -> '#065f46'
colorContrast(..., 'hex') // -> '#065f46'
colorContrast(..., 'rgb') // -> 'rgb(6, 95, 70)'
colorContrast(..., 'rgb-array') // -> [6, 95, 70]
colorContrast(..., 'hsl') // -> 'hsl(163, 88%, 20%)' (rounded)
colorContrast(..., 'hsl-array') // -> [163.14606741573033, 0.8811881188118811, 0.19803921568627453] (not rounded)
```
## Examples
*Arguments to `color-contrast()` wrapped onto multiple lines for clarity.*
InputOutputImage
```css
.container {
background-color: #0f172a;
color: color-contrast(
#0f172a vs
#e5e5e5, #171717
);
}
```
```css
.container {
background-color: #0f172a;
/*
picks the color in the list
(after "vs") that has the
highest contrast ratio with
the first color
*/
color: #e5e5e5;
}
```
```css
.container {
background-color: #6ee7b7;
color: color-contrast(
#6ee7b7 vs
#ecfdf5, #d1fae5,
#a7f3d0, #6ee7b7,
#34d399, #10b981,
#059669, #047857,
#065f46, #064e3b
to AA
);
}
```
```css
.container {
background-color: #6ee7b7;
/*
with a target contrast:
picks the first color
that meets or exceeds
the target contrast ratio
*/
color: #065f46; /* 5.41:1 */
}
```
```css
.container {
background-color: #c2410c;
color: color-contrast(
#c2410c vs
#e5e5e5, #171717
to AA
);
}
```
```css
.container {
background-color: #c2410c;
/*
defaults to black or white
if the target contrast cannot
be met with the provided colors
*/
color: #fff;
}
```
