precolor v1.0.0

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

Acknowledgment

Precolor was built by Joshua Elijah Sandoval.

License

Precolor is distributed under the MIT License.