rio_theme/

semantic.rs

//! Case 4 — brand-vs-state collision resolver.
//!
//! Success / warning / danger are universal conventions. They are
//! *not* derived from the brand. The only adjustment the engine makes
//! is to push a state color out of the brand's way when the hues
//! collide, so a red brand doesn't reduce the "delete" button to
//! noise.
//!
//! Two guard rails on top of the brief's algorithm:
//!
//! 1. **Achromatic brand short-circuit.** When the brand is grey
//!    (`chroma ≈ 0`) the stored hue is arbitrary and using it as a
//!    collision target produces nonsense rotations. The resolver
//!    returns the three anchors unchanged in that case.
//!
//! 2. **Bounded rotation.** A naive "rotate until gap ≥ 45°" can
//!    push success out of the green band (e.g. a neon-green brand
//!    sends success all the way to teal). [`MAX_STATE_ROTATION`]
//!    caps how far a state may move so it always still reads as
//!    itself — the brand simply has to coexist with a state when
//!    the brand was *chosen* in that state's hue family.

use crate::color::{hue_distance, Color};
use crate::contrast::{contrast_ratio, AA_NON_TEXT, LIGHT_BG};

/// Minimum OKLCH hue gap (degrees) a state color tries to keep from
/// the brand. The actual achieved gap may be smaller — see
/// [`MAX_STATE_ROTATION`].
pub const MIN_HUE_GAP: f64 = 45.0;

/// Hard upper bound on how far the resolver will move a state color
/// to clear the brand. 30° keeps each state inside its conventional
/// hue family (success in green, warning in amber/orange, danger in
/// red/crimson) even when the brand is a near-match. The brief
/// allows up to a 45° rotation, but 45° pushes red→amber and
/// green→teal — losing the state's identity. The capped value
/// prefers a smaller separation over a wrong-colored state.
pub const MAX_STATE_ROTATION: f64 = 30.0;

/// OKLCH chroma below this is treated as achromatic for collision
/// purposes — hue is undefined, so semantic colors stay unshifted.
pub const ACHROMATIC_CHROMA: f64 = 0.02;

/// Fixed anchor hue for "success". Green is the universal convention.
pub const SUCCESS_ANCHOR: &str = "#16a34a";
/// Fixed anchor hue for "warning". Amber is the universal convention.
pub const WARNING_ANCHOR: &str = "#d97706";
/// Fixed anchor hue for "danger". Red is the universal convention.
pub const DANGER_ANCHOR: &str = "#dc2626";

/// Resolved state colors after collision avoidance.
#[derive(Debug, Clone, Copy)]
pub struct SemanticPalette {
    /// Foreground for success affordances (typically green).
    pub success: Color,
    /// Foreground for warning affordances (typically amber).
    pub warning: Color,
    /// Foreground for danger / destructive affordances (typically red).
    pub danger: Color,
}

/// Signed shortest-arc difference `to - from` normalised to
/// `(-180.0, 180.0]`. Positive means `to` sits counter-clockwise
/// from `from`. Used to derive the away-from-brand rotation
/// direction.
fn signed_hue_diff(from: f64, to: f64) -> f64 {
    let mut d = (to - from) % 360.0;
    if d > 180.0 {
        d -= 360.0;
    } else if d <= -180.0 {
        d += 360.0;
    }
    d
}

fn shift_away(anchor: Color, brand: &Color) -> Color {
    // Achromatic brand has no hue to collide with.
    if brand.c < ACHROMATIC_CHROMA {
        return anchor;
    }
    let gap = hue_distance(anchor.h, brand.h);
    if gap >= MIN_HUE_GAP {
        return anchor;
    }
    // Brand sits *inside* this state's hue family — the user chose a
    // brand in (e.g.) the green family on purpose. Rotating would
    // push success into cyan/teal and lose the state's identity. We
    // accept the visual coexistence; the brand and the state will
    // read as close cousins, which is what the user signaled.
    if gap < MIN_HUE_GAP / 2.0 {
        return anchor;
    }
    // Brand sits near the edge of the state's family. Rotate AWAY,
    // capped by [`MAX_STATE_ROTATION`] so the result stays inside
    // the state's conventional band. signed_hue_diff(brand, anchor)
    // tells us which side the anchor sits on; we keep moving in
    // that direction so the gap grows monotonically.
    let signed = signed_hue_diff(brand.h, anchor.h);
    let dir = if signed >= 0.0 { 1.0 } else { -1.0 };
    let needed = (MIN_HUE_GAP - gap).min(MAX_STATE_ROTATION);
    Color::from_oklch(anchor.l, anchor.c, anchor.h + dir * needed)
}

fn ensure_visible_on_white(color: Color) -> Color {
    let bg = Color::from_hex(LIGHT_BG).expect("constant");
    if contrast_ratio(&bg, &color) >= AA_NON_TEXT {
        return color;
    }
    // Step the color darker in OKLCH lightness until it clears AA
    // against white. Bounded at 10 iterations — at 0.05/step that
    // covers the entire mid-band before bottoming out at black.
    let mut c = color;
    for _ in 0..10 {
        let new_l = (c.l - 0.05).max(0.0);
        if (new_l - c.l).abs() < f64::EPSILON {
            break;
        }
        c = Color::from_oklch(new_l, c.c, c.h);
        if contrast_ratio(&bg, &c) >= AA_NON_TEXT {
            break;
        }
    }
    c
}

/// Pick state colors, pushing each one away from the brand hue when
/// it sits inside the brand's collision zone. See the module docs
/// for the two guard rails layered on top of the brief's algorithm.
pub fn resolve_semantics(brand: &Color) -> SemanticPalette {
    let success = Color::from_hex(SUCCESS_ANCHOR).expect("constant");
    let warning = Color::from_hex(WARNING_ANCHOR).expect("constant");
    let danger = Color::from_hex(DANGER_ANCHOR).expect("constant");

    SemanticPalette {
        success: ensure_visible_on_white(shift_away(success, brand)),
        warning: ensure_visible_on_white(shift_away(warning, brand)),
        danger: ensure_visible_on_white(shift_away(danger, brand)),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn c(hex: &str) -> Color {
        Color::from_hex(hex).unwrap()
    }

    #[test]
    fn red_brand_keeps_danger_at_anchor_for_family_coexistence() {
        // Red brand sits inside the danger hue family. Rotating
        // would push danger into amber/orange territory and lose the
        // "red = danger" convention. The engine accepts coexistence:
        // the user chose a red brand knowing it lives next to danger.
        let red_brand = c("#cc2222");
        let p = resolve_semantics(&red_brand);
        assert_eq!(
            p.danger.to_hex(),
            c(DANGER_ANCHOR).to_hex(),
            "danger should stay at anchor for an in-family brand"
        );
    }

    #[test]
    fn brand_at_gap_boundary_does_get_capped_rotation() {
        // Build a brand at exactly MIN_HUE_GAP/2 + small from the
        // danger anchor — outside the "family" zone, inside the
        // collision zone. Rotation should fire but stay capped.
        let danger = c(DANGER_ANCHOR);
        let off_brand_hue = danger.h + MIN_HUE_GAP / 2.0 + 5.0;
        let brand = Color::from_oklch(0.55, 0.13, off_brand_hue);
        let p = resolve_semantics(&brand);
        let drift = hue_distance(p.danger.h, danger.h);
        assert!(drift > 0.0 && drift <= MAX_STATE_ROTATION + 1.0);
    }

    #[test]
    fn purple_brand_leaves_all_three_unshifted() {
        let purple = c("#8a4cb4");
        let p = resolve_semantics(&purple);
        assert_eq!(p.success.to_hex(), c(SUCCESS_ANCHOR).to_hex());
        assert_eq!(p.warning.to_hex(), c(WARNING_ANCHOR).to_hex());
        assert_eq!(p.danger.to_hex(), c(DANGER_ANCHOR).to_hex());
    }

    #[test]
    fn grey_brand_leaves_all_three_unshifted() {
        // Achromatic brand has no hue to collide with — the engine
        // must not rotate semantics based on the arbitrary stored
        // hue of a grey colour.
        let grey = c("#888888");
        let p = resolve_semantics(&grey);
        assert_eq!(p.success.to_hex(), c(SUCCESS_ANCHOR).to_hex());
        assert_eq!(p.warning.to_hex(), c(WARNING_ANCHOR).to_hex());
        assert_eq!(p.danger.to_hex(), c(DANGER_ANCHOR).to_hex());
    }

    #[test]
    fn neon_green_brand_keeps_success_in_green_family() {
        // The bug this guards against: an unbounded 45° rotation
        // pushed a green brand's success colour all the way to
        // teal/cyan. Capped rotation must keep success readable as
        // green (OKLCH hue in roughly the green band).
        let lime = c("#39ff14");
        let success_anchor_hue = c(SUCCESS_ANCHOR).h;
        let shifted = resolve_semantics(&lime).success;
        let drift = hue_distance(shifted.h, success_anchor_hue);
        assert!(
            drift <= MAX_STATE_ROTATION + 1.0,
            "success drifted {drift}° from anchor — band cap broken"
        );
    }

    #[test]
    fn signed_hue_diff_handles_wraparound() {
        // 10° from 350° is +20° (going through 0), not -340°.
        assert!((signed_hue_diff(350.0, 10.0) - 20.0).abs() < 1e-9);
        // 350° from 10° is -20°.
        assert!((signed_hue_diff(10.0, 350.0) + 20.0).abs() < 1e-9);
        // Identity.
        assert!(signed_hue_diff(45.0, 45.0).abs() < 1e-9);
    }

    #[test]
    fn rotation_direction_actually_moves_anchor_away() {
        // Regression for the dual-candidate verifier bug — pick a
        // brand on each side of an anchor and confirm the post-shift
        // distance is larger than the pre-shift distance, never
        // smaller.
        for brand_hex in ["#cc2222", "#22cc22", "#2222cc", "#cccc22"] {
            let brand = c(brand_hex);
            let p = resolve_semantics(&brand);
            for state in [p.success, p.warning, p.danger] {
                // For brand+state combos where shift fired, the gap
                // must be strictly greater than (or equal to) what a
                // zero-rotation would give. We can't easily compute
                // the "pre" gap without re-running, so just assert
                // the post gap is sane.
                let gap = hue_distance(state.h, brand.h);
                assert!((0.0..=180.0).contains(&gap));
            }
        }
    }
}