precolor

Powerful preprocessor tools for an accessible color palette.

Add it to your project now via installation by NPM:

npm install precolor --save-dev

---

What is Precolor?

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.

Prerequisite Installation

Step 1: Install NPM

To begin, you will need NPM (Node Package Manager).
Here is an installation guide.

Step 2: Install Sass

Once you have NPM installed, installation of Sass is easy.
Run the following terminal command:

npm install -g sass

You're all set!

Getting Started

Installation

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/.

Importing

Forwarding & Configuration

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.

Using & Namespacing

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).

Default Colors

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

Color Schemes

Differing color schemes can improve your website's visibility during certain times of the day. It is a great quality of life feature!

Color Schemes (Mixin)

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:

1. $light - The light (default) color.
2. $dark - The dark color.

// Outputs color $light and $dark:
@include color-schemes using ($color) {
	@debug $color;
}

Light and Dark (Mixins)

Mixins light and dark build a prefers-color-scheme media query for users requesting light or dark mode respectively.

@include light {
	...
}

@include dark {
	...
}

Color Contrast

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.

High Contrast

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:

1. $color-list - The color set to be compared.
2. $background - The color to compare contrast against.
3. $target - The contrast-ratio value to be met.

// Outputs the color blue:
@debug high-contrast(red green blue, white);

Contrast Color

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:

1. $color-list - The color set to be compared.
2. $background - The color to compare contrast against.
3. $target - The contrast-ratio value to be met.

// Outputs the color green:
@debug contrast-color(red green blue, white, 4.5);

Contrast Ratio

Function contrast-ratio gets the contrast-ratio between two colors as a number from 1 to 21.

contrast-ratio($color1, $color2);

Usage & Parameters:

1. $color1 - First color value.
2. $color2 - Second color value.

// Outputs the number 21:
@debug contrast-ratio(white, black);

A11y (Accessibility)

Function a11y returns a contrast-ratio value associated with accessibility $keywords.

a11y($keywords);

Usage & Parameters:

1. $keywords - An unquoted string of accessibility keywords.
   Defaults to 7. 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);

Contrast (Mixin)

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:

1. $no-preference - The default value.
2. $more - High contrast value.
3. $less - Low contrast value.
4. $custom - None of the above. The client has requested a custom palette by users of forced-colors: active.

// Outputs contrast-ratios 4.5 (no-preference) and 7 (more):
@include contrast using ($ratio) {
	@debug $ratio;
}

Color Luminance

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.

Luminance

Function luminance calculates the relative luminance of a given $color from 0 to 1.

luminance($color);

Usage & Parameters:

1. $color - The color to calculate against.

// Outputs the number 1:
@debug luminance(white);

Shade or Tint and Tone

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:

1. $color - The color to modify.
2. $amount - A percentage (ranging from 0% to 100%).

// Outputs the color teal:
@debug shade(cyan, 50%);
// Outputs the color silver:
@debug tint(gray, 50%);
// Outputs the color gray:
@debug tone(white, 100%);

Color Shift

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:

1. $color - The color to modify.
2. $amount - A percentage (ranging from 0% to 100%).

// Outputs the color gray:
@debug color-shift(white, 50%);
@debug color-shift(black, 50%);

Color Weight

Function color-weight changes the HSL lightness attribute of $color by a given $weight.

color-weight($color, $weight);

Usage & Parameters:

1. $color - The color to modify.
2. $weight - Integer ranging from 0 to 1000 representing white to black.

// Outputs the color gray:
@debug color-weight(white, 500);

Light and Dark (Functions)

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:

1. $color-list - Color set to compare luminance of.

// Outputs red:
@debug light(red, green, blue);
// Outputs blue:
@debug dark(red, green, blue);

Is Light or Dark

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:

1. $color - The color to measure luminance of.

// Outputs false:
@debug is-light(green);
// Outputs true:
@debug is-dark(blue);

Sass Color Module

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

Acknowledgment

Precolor was built by Joshua Elijah Sandoval.

License

Precolor is distributed under the MIT License.