accessible-colors/dist/index.d.ts

Utility functions for working with colors in adherence to WCAG 2.1 guidelines.

/**
 * Original luminance function (used here, WCAG2.0 standard):
 * @link https://www.w3.org/TR/WCAG20/#relativeluminancedef
 * L = 0.2126 * R + 0.7152 * G + 0.0722 * B
 * @param color (r, g, b) color
 * @returns a number between 0 and 1 representing the linear luminance of the color
 */
declare const getLuminance: (color: string) => number | null;
/**
 * @link https://www.w3.org/TR/WCAG20/#contrast-ratiodef
 * Produces a contrast ratio between two colors between 1 and 21. This
 * is expressed as 1:1 - 21:1, where contrast of 4.5:1 is considered
 * to be the minimum for normal text and 3:1 for large text.
 * @param color1 - first color to compare in hex format (e.g. #000000)
 * @param color2 - second color to compare in hex format (e.g. #ffffff)
 * @param precision - number of decimal places to round to
 * @returns
 */
declare const getContrast: (color1: string | null, color2: string | null, precision?: number) => number | null;
/**
 * isContrasting returns true if the constrast ratio between two specified colors is at least the specified ratio.
 * @param color1 - first color to compare in hex format (e.g. #000000)
 * @param color2 - second color to compare in hex format (e.g. #ffffff)
 * @param ratio - the contrast ratio to compare against. Should be between 1 and 21
 * @returns - true if the contrast ratio is at least the specified ratio
 */
declare const isContrasting: (color1: string, color2: string, ratio: number) => boolean | null;
/**
 * isAAContrast returns true if the constrast ratio between two specified colors satisfies the WCAG 2.0 AA standard
 * @link https://www.w3.org/WAI/GL/UNDERSTANDING-WCAG20/visual-audio-contrast7.html
 * @param color1 - first color to compare in hex format (e.g. #000000)
 * @param color2 - second color to compare in hex format (e.g. #ffffff)
 * @param large Large text is defined as at least 14 point (18.66px) + bold, or 18 point (24px) without bold. @link https://www.w3.org/WAI/GL/UNDERSTANDING-WCAG20/visual-audio-contrast7.html#larger-scaledef
 * @returns - true if the contrast ratio is at least 4.5:1 (normal text) or 3:1 (large text)
 */
declare const isAAContrast: (color1: string, color2: string, large?: boolean) => boolean | null;
/**
 * isAAAContrast returns true if the constrast ratio between two specified colors satisfies the WCAG 2.0 AAA standard
 * @link https://www.w3.org/WAI/GL/UNDERSTANDING-WCAG20/visual-audio-contrast7.html
 * @param color1 - first color to compare in hex format (e.g. #000000)
 * @param color2 - second color to compare in hex format (e.g. #ffffff)
 * @param large Large text is defined as at least 14 point (18.66px) + bold, or 18 point (24px) without bold. @link https://www.w3.org/WAI/GL/UNDERSTANDING-WCAG20/visual-audio-contrast7.html#larger-scaledef
 * @returns - true if the contrast ratio is at least 7:1 (normal text) or 4.5:1 (large text)
 */
declare const isAAAContrast: (color1: string, color2: string, large?: boolean) => boolean | null;
/**
 * randomColor will return a random color in hex format (e.g. `'#000000'`)
 * @returns a random color in hex format (e.g. `'#000000'`)
 */
declare const randomColor: () => string;
/**
 * getRandomAAColor will return a random color that is accessible based on the
 * WCAG 2.0 AA standard, which requires a contrast ratio of at least 4.5:1.
 * @param background - the background color to use for the contrast ratio calculation.
 * @param large - whether the text should be considered large, adjusting the contrast ratio requirement to 3:1.
 * @returns a random color that is accessible based on the WCAG 2.0 AA standard.
 */
declare const getRandomAAColor: (background: string, large?: boolean) => string | null;
/**
 * getRandomAAAColor will return a random color that is accessible based on the
 * WCAG 2.0 AAA standard, which requires a contrast ratio of at least 7:1. It will
 * take into account the luminance of the background color (hash).
 * @param background - the background color to use for the contrast ratio calculation.
 * @param large - whether the text should be considered large, adjusting the contrast ratio requirement to 4.5:1.
 * @returns a random color that is accessible based on the WCAG 2.0 AAA standard.
 */
declare const getRandomAAAColor: (background: string, large?: boolean) => string | null;
/**
 * suggestAAColor will return a close accessible color to the specified color with WCAG AA compatibility.
 * @param colorToChange - the color we want to find a close accessible color for.
 * @param colorToKeep - the color we want to keep the contrast ratio with.
 * @param large - whether the text should be considered large, adjusting the contrast ratio requirement to 3:1.
 * @returns a close accessible color to the specified `colorToChange` relative to the `colorToKeep`, or `null` if no accessible color can be found.
 */
declare const suggestAAColorVariant: (colorToChange: string, colorToKeep: string, large?: boolean) => string | null;
/**
 * suggestAAAColor will return a close accessible color to the specified color with WCAG AAA compatibility.
 * @param colorToChange - the color we want to find a close accessible color for.
 * @param colorToKeep - the color we want to keep the contrast ratio with.
 * @param large - whether the text should be considered large, adjusting the contrast ratio requirement to 4.5:1.
 * @returns a close accessible color to the specified `colorToChange` relative to the `colorToKeep`, or `null` if no accessible color can be found.
 */
declare const suggestAAAColorVariant: (colorToChange: string, colorToKeep: string, large?: boolean) => string | null;

export { getContrast, getLuminance, getRandomAAAColor, getRandomAAColor, isAAAContrast, isAAContrast, isContrasting, randomColor, suggestAAAColorVariant, suggestAAColorVariant };