theme_contrast.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/view/theme.hpp>
#include <string>
#include <vector>
#include <optional>
 
namespace pulp::view {
 
// ── WCAG Contrast Utilities ─────────────────────────────────────────────────
// Implements WCAG 2.1 contrast ratio calculations for accessible theme design.

float relative_luminance(Color c);

float contrast_ratio(Color a, Color b);

enum class ContrastLevel {
    aa_normal,    // 4.5:1 for normal text (< 18pt or < 14pt bold)
    aa_large,     // 3.0:1 for large text (>= 18pt or >= 14pt bold)
    aaa_normal,   // 7.0:1 for AAA normal text
    aaa_large     // 4.5:1 for AAA large text
};

float min_contrast_for_level(ContrastLevel level);

bool meets_contrast(Color foreground, Color background, ContrastLevel level = ContrastLevel::aa_normal);

Color auto_contrast_foreground(Color background, ContrastLevel level = ContrastLevel::aa_normal);

std::optional<Color> adjust_for_contrast(Color foreground, Color background,
                                          ContrastLevel level = ContrastLevel::aa_normal);
 
// ── HSL Conversion Utilities ────────────────────────────────────────────────
// Delegates to Color::to_hsl() / Color::from_hsl() — these wrappers exist
// for backward compatibility with code that uses the free-function API.
 
using HSL = canvas::Color::HSL;
 
inline HSL rgb_to_hsl(Color c) { return c.to_hsl(); }
inline Color hsl_to_rgb(HSL hsl, float alpha = 1.0f) { return Color::from_hsl(hsl, alpha); }

Color shift_hue(Color c, float degrees);

Color adjust_lightness(Color c, float delta);

Color blend_colors(Color a, Color b, float t);

Color with_alpha(Color c, float alpha);
 
// ── Theme Contrast Validation ───────────────────────────────────────────────
 
struct ContrastIssue {
    std::string foreground_token;
    std::string background_token;
    float ratio;
    ContrastLevel required_level;
};

std::vector<ContrastIssue> validate_theme_contrast(const Theme& theme,
                                                    ContrastLevel level = ContrastLevel::aa_normal);

Theme auto_fix_contrast(const Theme& theme, ContrastLevel level = ContrastLevel::aa_normal);
 
} // namespace pulp::view