Accessibility Module

The accessibility module provides functions for creating WCAG-compliant color combinations and maximizing contrast ratios.

Contrast Analysis

chromo_map.contrast_ratio(color1, color2)

Calculate the contrast ratio between two colors.

Uses the WCAG 2.1 formula for contrast ratio.

Parameters:

• color1 (Color) – The first color.

• color2 (Color) – The second color.

Returns:

The contrast ratio (1:1 to 21:1).

Return type:

float

Examples

Calculate contrast ratio between black and white:

from chromo_map import contrast_ratio
ratio = contrast_ratio('black', 'white')
print(f"Contrast ratio: {ratio:.1f}:1")

Contrast ratio: 21.0:1

Calculate the contrast ratio between two colors according to WCAG guidelines.

from chromo_map import Color, contrast_ratio

color1 = Color('#ff0000')  # Red
color2 = Color('#ffffff')  # White

ratio = contrast_ratio(color1, color2)
print(f"Contrast ratio: {ratio:.2f}")  # Should be ~4.0

chromo_map.is_accessible(color1, color2, level='AA')

Check if two colors have sufficient contrast for accessibility.

Parameters:

• color1 (Color) – The first color (typically text).

• color2 (Color) – The second color (typically background).

• level (str, default 'AA') – The WCAG level to check against (‘AA’ or ‘AAA’).

Returns:

True if the contrast ratio meets the specified level.

Return type:

bool

Examples

Check if black text on white background is accessible:

from chromo_map import is_accessible
is_accessible('black', 'white')

True

Check if a color combination meets WCAG accessibility standards.

from chromo_map import is_accessible

# Check AA compliance (4.5:1 for normal text)
accessible_aa = is_accessible('#666666', 'white', level='AA')

# Check AAA compliance (7:1 for normal text)
accessible_aaa = is_accessible('#666666', 'white', level='AAA')

Color Optimization

chromo_map.find_accessible_color(base_color, target_color, level='AA', adjust_lightness=True)

Find an accessible version of a color by adjusting it.

Parameters:

• base_color (Color) – The color to adjust.

• target_color (Color) – The color to ensure accessibility against.

• level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

• adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

Returns:

An accessible version of the base color.

Return type:

Color

Examples

Find an accessible version of gray against white:

from chromo_map import find_accessible_color
accessible = find_accessible_color('#888888', 'white')
print(f"Accessible color: {accessible.hex}")

Accessible color: #595959

Find an accessible version of a color that meets WCAG requirements.

from chromo_map import find_accessible_color

# Make a color accessible against white background
original = '#ff6b6b'  # Light red
accessible = find_accessible_color(original, 'white', level='AA')

print(f"Original: {original}")
print(f"Accessible: {accessible.hex}")

Advanced Contrast Optimization

chromo_map.find_maximal_contrast_iterative(base_color, target_color, level='AA', adjust_lightness=True, step_size=0.1, max_attempts=50)

Find maximal contrast using simple iterative approach.

This approach incrementally adjusts the color until it meets the contrast requirement. Simple but may not find the optimal solution.

Parameters:

• base_color (Color) – The color to adjust.

• target_color (Color) – The color to ensure accessibility against.

• level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

• adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

• step_size (float, default 0.1) – The step size for adjustments.

• max_attempts (int, default 50) – Maximum number of adjustment attempts.

Returns:

The adjusted color with maximal contrast found.

Return type:

Color

Examples

Find maximal contrast iteratively:

from chromo_map import find_maximal_contrast_iterative
result = find_maximal_contrast_iterative('#888888', 'white')
print(f"Iterative result: {result.hex}")

Iterative result: #595959

Enhanced iterative approach for finding maximum contrast:

from chromo_map import find_maximal_contrast_iterative

# Find maximum contrast using iterative approach
optimized = find_maximal_contrast_iterative('#888888', 'white')
print(f"Optimized color: {optimized.hex}")

chromo_map.find_maximal_contrast_binary_search(base_color, target_color, level='AA', adjust_lightness=True, precision=0.001)

Find maximal contrast using binary search approach.

This approach uses binary search to efficiently find the optimal adjustment factor that maximizes contrast while meeting accessibility requirements.

Parameters:

• base_color (Color) – The color to adjust.

• target_color (Color) – The color to ensure accessibility against.

• level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

• adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

• precision (float, default 0.001) – The precision for binary search convergence.

Returns:

The adjusted color with maximal contrast found.

Return type:

Color

Examples

Find maximal contrast using binary search:

from chromo_map import find_maximal_contrast_binary_search
result = find_maximal_contrast_binary_search('#888888', 'white')
print(f"Binary search result: {result.hex}")

Binary search result: #595959

Binary search approach for precise contrast optimization:

from chromo_map import find_maximal_contrast_binary_search

# Find maximum contrast using binary search
optimized = find_maximal_contrast_binary_search(
    '#888888', 'white', precision=0.001
)

chromo_map.find_maximal_contrast_optimization(base_color, target_color, level='AA', method='golden_section')

Find maximal contrast using mathematical optimization.

This approach uses mathematical optimization techniques to find the adjustment that maximizes contrast ratio while meeting accessibility requirements.

Parameters:

• base_color (Color) – The color to adjust.

• target_color (Color) – The color to ensure accessibility against.

• level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

• method (str, default 'golden_section') – The optimization method to use (‘golden_section’ or ‘gradient_descent’).

Returns:

The adjusted color with maximal contrast found.

Return type:

Color

Examples

Find maximal contrast using optimization:

from chromo_map import find_maximal_contrast_optimization
result = find_maximal_contrast_optimization('#888888', 'white')
print(f"Optimization result: {result.hex}")

Optimization result: #595959

Mathematical optimization approach for absolute maximum contrast:

from chromo_map import find_maximal_contrast_optimization

# Find absolute maximum contrast
optimized = find_maximal_contrast_optimization(
    '#888888', 'white', method='golden_section'
)

When to Use Each Method

find_accessible_color

Use when you need basic WCAG compliance quickly. Good for most web applications.

find_maximal_contrast_iterative

Use when you want better results than basic accessibility but don’t need perfect optimization.

find_maximal_contrast_binary_search

Use when you need precise, consistent results with good performance.

find_maximal_contrast_optimization

Use when you need the absolute best contrast possible and can afford computational cost.

Performance Comparison

Method Performance

Method	Speed	Accuracy	Best Use Case
find_accessible_color	Fastest	Good	Basic compliance
iterative	Fast	Better	Balanced performance
binary_search	Medium	High	Automated systems
optimization	Slower	Highest	Maximum quality

WCAG Guidelines

The Web Content Accessibility Guidelines (WCAG) define contrast requirements:

• AA Level: 4.5:1 for normal text, 3:1 for large text

• AAA Level: 7:1 for normal text, 4.5:1 for large text

• Large text: 18pt+ or 14pt+ bold

All accessibility functions in chromo-map follow these standards.