Add it to your project now via installation by NPM:
npm install precolor --save-dev
Precolor is a collection of CSS color manipulation tools written in Sass (SCSS). Purposely designed to reduce CSS color complexity and increase accessibility on the web.
To begin, you will need NPM (Node Package Manager).
Here is an installation guide.
Once you have NPM installed, installation of Sass is easy.
Run the following terminal command:
npm install -g sass
You're all set!
Navigate to the root directory of your project of choice.
Run the following command:
npm install precolor --save-dev
This will install Precolor locally in the directory node_modules/precolor/
.
Import the package with the Sass @forward
rule in a new file named _precolor.scss
.
@forward "node_modules/precolor/";
In addition to being an accessible entry point: @forward
allows for the configuration of a module's !default
variables.
@forward "node_modules/precolor/" with (
$variable: value !default,
...
);
The !default
flag after the variable value is optional, but it allows further configuration by other stylesheets.
Use the package with the Sass @use
rule in a new file named styles.scss
.
@use "precolor" as color;
In the example above: color
is the namespace of the module. Members of the module can be accessed by prepending color.
. Ex: color.$primary
.
You can omit the namespace using *
(wildcard).
Having a consistent color palette is critical to visual design. Precolor provides defaults based on CSS named colors, as well as a more deliberate and concise palette. These colors are also mapped. Named $colors
and $color-palette
respectively.
Color Palette | Description | RGB Hex Value | CSS Named Color |
---|---|---|---|
$primary |
The most frequent color used. It represents primary user-interface elements. | #5490b8 |
$blue |
$secondary |
Optional secondary color used to accent user-interface elements. | #727C83 |
$gray |
$success |
Represents when a user action has been successful. | #74bf80 |
$green |
$danger |
Represents a critical action or failure. | #EF6461 |
$red |
$warning |
Represents a potentially dangerous user action. | #FFCB47 |
$yellow |
$info |
Represents information to the user. | #6bcee7 |
$cyan |
$light |
The primary light color. Commonly used for backgrounds. | #FBFBFB |
$white |
$dark |
The primary dark color. Commonly used for backgrounds. | #18181C |
$black |
#c9c8d6 |
$silver |
||
#b91c68 |
$maroon |
||
#F47C98 |
$pink |
||
#b350ed |
$purple |
||
#9892C8 |
$indigo |
||
#df11af |
$fuchsia |
||
#00ff6e |
$lime |
||
#389269 |
$olive |
||
#EE8434 |
$orange |
||
#BB946C |
$brown |
||
#00305f |
$navy |
||
#2a9186 |
$teal |
||
$cyan |
$aqua |
Differing color schemes can improve your website's visibility during certain times of the day. It is a great quality of life feature!
Mixin color-schemes
builds prefers-color-scheme
media queries using differing colors.
@include color-schemes($light: $light, $dark: $dark)
Usage & Parameters:
Each parameter represents a value for the prefers-color-scheme
media query:
$light
- The light (default) color.$dark
- The dark color.
// Outputs color $light and $dark:
@include color-schemes using ($color) {
@debug $color;
}
Mixins light
and dark
build a prefers-color-scheme
media query for users requesting light or dark mode respectively.
@include light {
...
}
@include dark {
...
}
Ensuring color is intelligible is crucial to designing a website anyone can use. If nobody can see your website, it is difficult for everyone to stay on your website.
Function high-contrast
narrows down a $color-list
to the first color that is closest to the $target
contrast-ratio compared to $background
.
high-contrast($color-list, $background, $target: 21);
Usage & Parameters:
$color-list
- The color set to be compared.$background
- The color to compare contrast against.$target
- The contrast-ratio value to be met.
// Outputs the color blue:
@debug high-contrast(red green blue, white);
Function contrast-color
filters a $color-list
using the high-contrast
function and defaults to tint the color to meet the $target
contrast-ratio compared to $background
.
contrast-color($color-list, $background, $target: 7);
Usage & Parameters:
$color-list
- The color set to be compared.$background
- The color to compare contrast against.$target
- The contrast-ratio value to be met.
// Outputs the color green:
@debug contrast-color(red green blue, white, 4.5);
Function contrast-ratio
gets the contrast-ratio between two colors as a number from 1
to 21
.
contrast-ratio($color1, $color2);
Usage & Parameters:
$color1
- First color value.$color2
- Second color value.
// Outputs the number 21:
@debug contrast-ratio(white, black);
Function a11y
returns a contrast-ratio value associated with accessibility $keywords
.
a11y($keywords);
Usage & Parameters:
$keywords
- An unquoted string of accessibility keywords.
Defaults to7
. Can accept a number.
// Outputs the number 4.5:
@debug a11y(aa);
@debug a11y(aaa large);
// Outputs the number 3:
@debug a11y(aa large);
@debug a11y(aa ui);
// Outputs the number 7:
@debug a11y(aaa);
Mixin contrast
builds prefers-contrast
media queries using differing preferences.
@include contrast($no-preference: aa, $more: aaa, $less: null, $custom: null)
Usage & Parameters:
Each parameter represents an a11y
function value for the prefers-contrast
media query:
$no-preference
- The default value.$more
- High contrast value.$less
- Low contrast value.$custom
- None of the above. The client has requested a custom palette by users offorced-colors: active
.
// Outputs contrast-ratios 4.5 (no-preference) and 7 (more):
@include contrast using ($ratio) {
@debug $ratio;
}
Differing levels of color luminance can portray depth and interactivity in a design. Presenting a clear visual hierarchy and signaling to the user that the application is responding to their inputs.
Function luminance
calculates the relative luminance of a given $color
from 0
to 1
.
luminance($color);
Usage & Parameters:
$color
- The color to calculate against.
// Outputs the number 1:
@debug luminance(white);
Functions shade
, tint
and tone
modify an attribute of a $color
by a given $amount
.
Shade mixes in black
, tint mixes in white
, and tone mixes in gray
.
shade($color, $amount);
tint($color, $amount);
tone($color, $amount);
Usage & Parameters:
$color
- The color to modify.$amount
- A percentage (ranging from0%
to100%
).
// Outputs the color teal:
@debug shade(cyan, 50%);
// Outputs the color silver:
@debug tint(gray, 50%);
// Outputs the color gray:
@debug tone(white, 100%);
Function color-shift
modifies $color
by a given $amount
alternating between shade
and tint
functions based on its existing relative luminance.
color-shift($color, $amount);
Usage & Parameters:
$color
- The color to modify.$amount
- A percentage (ranging from0%
to100%
).
// Outputs the color gray:
@debug color-shift(white, 50%);
@debug color-shift(black, 50%);
Function color-weight
changes the HSL lightness attribute of $color
by a given $weight
.
color-weight($color, $weight);
Usage & Parameters:
$color
- The color to modify.$weight
- Integer ranging from0
to1000
representingwhite
toblack
.
// Outputs the color gray:
@debug color-weight(white, 500);
Functions light
and dark
narrow down a $color-list
to the color whose relative luminance is lightest or darkest respectively.
light($color-list...);
dark($color-list...);
Usage & Parameters:
$color-list
- Color set to compare luminance of.
// Outputs red:
@debug light(red, green, blue);
// Outputs blue:
@debug dark(red, green, blue);
Functions is-light
and is-dark
return a boolean (true or false) on whether relative luminance of $color
is light or dark respectively.
is-light($color);
is-dark($color);
Usage & Parameters:
$color
- The color to measure luminance of.
// Outputs false:
@debug is-light(green);
// Outputs true:
@debug is-dark(blue);
The Sass language itself has many color functions of its own. These are aptly forwarded in Precolor.
https://sass-lang.com/documentation/modules/color/
Module Function | Description | Snippet | Output |
---|---|---|---|
alpha | Retrieves alpha channel of color as a number from 0 to 1 . |
alpha(rgba(0, 0, 0, 0.5)) |
0.5 |
blackness | Retrieves color HWB blackness as a percentage from 0% to 100% . |
blackness(black) |
100% |
blue | Retrieves blue channel of color as a number from 0 to 255 . |
blue(#0000FF) |
255 |
grayscale | Removes saturation from color. | grayscale(orange) |
gray |
green | Retrieves green channel of color as a number from 0 to 255 . |
green(#00FF00) |
255 |
hue | Retrieves color hue value between 0deg and 360deg . |
hue(yellow) |
60deg |
hwb | Creates color from hue, whiteness and blackness. Optionally alpha transparency. | hwb(180deg, 0%, 50%) |
teal |
invert | Modifies color and outputs its negative. | invert(white, 100%) |
black |
lightness | Retrieves color HSL lightness as a percentage from 0% to 100% . |
lightness(purple) |
25% |
red | Retrieves red channel of color as a number from 0 to 255 . |
red(#FF0000) |
255 |
saturation | Retrieves color HSL saturation as a percentage from 0% to 100% . |
saturation(brown) |
60% |
whiteness | Retrieves color HWB whiteness as a percentage from 0% to 100% . |
whiteness(white) |
100% |
color-adjust | Modifies color properties by fixed amounts. Learn More. | color-adjust(lime, $blackness: 50%) |
green |
color-change | Modifies color properties by changing them to new values. Learn More. | color-change(yellow, $green: 0) |
red |
color-complement | Retrieves color RGB complement by rotating hue by 180deg . |
color-complement(blue) |
yellow |
color-mix | Retrieves color by mixing two colors together by percentage. Learn More. | color-mix(lime, blue, 50%) |
teal |
color-scale | Modifies color properties by fluidly scaling them. Learn More. | color-scale(green, $green: 100%) |
lime |
Precolor was built by Joshua Elijah Sandoval.
Precolor is distributed under the MIT License.