Docs
Everything You Need to Know
Color
Utility Methods
UIColor(colorValue)
ChocolateChip-UI has several sophisticated methods for manipulating color. These allow you to do things such as determine if text should be darker or light for legibility based on the item's background color. To pull these types of calculations off, ChocolateChip-UI uses the function UIColor(colorValue). This method takes a string as a hex or rgb value and converts it into an object. This object has two methods:
- toHex()
- toRGB()
You must use the new keyword when creating a color object:
// Create color object:
const colorObj = new UIColor('#ff0000')
// or:
const colorObj2 = new UIColor('rgb(255, 0, 0)')
With your color converted to an object, you can easily get the hex or RGB value of your color, or use it to do a number of other operations explained below.
Calculate Text Color for Legibility
$.calculateBrightness(color)
ChocolateChip-UI can calculate color contrast differently from generic contrast methods. Generic contrast conversion can easily result in text that is too dark for the mushier shades of olive, brown, violet and purple. To get around this high failure rate, we use the YIQ color algorithm. This takes into account the human eye's sensitivity to changes in the orange-blue range, and less sensitivity to changes in the purple-green range. ChocolateChip-UI's $.calculateBrightness method the brightness of a color.
The YIQ formula using red, green and blue is:
const brightness = ((r x .299) + (g x .587) + (b x .114))
Brightness
When we say brightness, we mean perceived luminance. Luminance is the measure of the intensity of light that reaches the eye. Brightness is how our eye and mind perceive that luminance.
Now that we can calculate a color's brightness, what could we do with it? Well, you might have a colored navbar with transparent buttons in it. Using the navbar's brightness, you can calculate whether the button text needs to be light or dark. This improves legibility. Using ChocolateChip-UI's color methods, you can do the following:
// Get the background color of the nav:
const backgroundColor = $('nav').css('background-color')
// Find out what the brightness of the background is:
const brightness = $.calculateBrightness(backgroundColor)
// A brightness greater than 139 would need dark text.
// Similarly, a brightness less than 139 would need light text.
// Taking this into account, we can create a legible text color:
const textColor = (brightness < 139) ? "#fafafa" : "#333"
// Set the color of the nav buttons based on the above value:
$('nav > button').css('color', textColor)
Testing Brightness
As you may have noticed above, we use 139 as the testing point for brightness. If a color has a brightness less than 139, the text should be light, if the brightness is greater than 139, the text should be dark. You might see people advocating use of 150 as the brightness check. This results in light text on light greens, which are impossible to read. Similarly, you might see use of 128. This results in dark text on charcoal grays and saturated colors. We settled on 139 since this works best with charcoals, oranges, violets and greens. You could use 138 to 140 without problem. You can see our version in action in this example where the text color is calculated during page load based on the background color. Feel free to use the brightness check that works for you.
When using a brightness value, think of it like RGB. A value of 0 would be black and a value of 255 would be white. You need to find an intermediate value that works for you.
Be aware that the color calibration of your monitor will affect how you see this working. It's always best to check color contrast using the default color profile for your monitor, since that's what most people use. Also check how your choice looks on the target device.
Test Background Colors
You can test what text will look like over a background color using the color picker below. As you adjust the color, the background color will update and the text color will be updated for legibility, either light or dark. You can also just enter a hex, rgb or color name value into the input below the color picker and hit Enter.
Choose a Color:
Lighten a Color
$.lightenColor(colorValue, percent)
You can programatically lighten a color by a designated percentage using this method. It takes a hex value:
// Lighten a hex color by 20%:
const lighterHexColor = $.lightenColor('#ff0000', 20)
// returns #ff3333
To use an RGB color with this, you can convert it to hex like so:
// Convert RGB to hex:
const newHexColor = new UIColor('rgb(255, 0, 0)').toHex()
// Lighten a hex color by 50%:
const lighterHexColor = $.lightenColor(newHexColor, 50)
// returns #ff7f7f
Darken a Color
$.darkenColor(colorValue, percent)
You can programatically darken a color by a designated percentage using this method. It takes a hex or rgb value:
// Darken a hex color by 20%:
const darkerHexColor = $.darkenColor('#ff0000', 20)
// returns #cc0000
To use an RGB color with this, you have to convert it to hex:
// Convert RGB to hex:
const newHexColor = new UIColor('rgb(255, 0, 0)').toHex()
// Darken a hex color by 50%:
const darkerHexColor = $.darkenColor('#ff0000', 50)
// returns #800000
Importing Color Utilities
To use these color utilities, you'll need to import them into your app. If you create your project for Android with the -o android flag, it already imports these in order to support the Android Material Design touch ripple effect. If your app is using the iOS theme and you want to use these utilities, you need to import them. To do so, just include the following in your app.js file:
import {UIColor} from './src/widgets/color-contrast'