From d22ee791598a61c2808e9f1cad60620df78fdca9 Mon Sep 17 00:00:00 2001 From: Noah <2+noah@noreply.gitea.bluefla.re> Date: Wed, 4 Nov 2026 13:40:10 -0600 Subject: [PATCH] Keep every coloured text readable in light and dark themes Checked in real system dark and light mode on macOS (SkyLight theme switch on the M1, restored afterwards), Windows 11 (the app-mode setting, run on the VM's desktop) and Linux (Adwaita and Adwaita:dark), measuring each screenshot's text against its background with the WCAG contrast formula. The app's own colours fell short on every platform. The fixed firmware hues were 2.6 to 3.9:1 (LuxOS gold and ePIC blue on light, Alkane navy, Braiins purple and Bixbit red on dark). The hashrate greens and temperature purples were about 4:1, and the play/pause icons about 2:1 on light buttons. - readable()/readable_at(): nudge a colour toward black (light theme) or white (dark theme), keeping its hue, until it reaches 4.5:1 for text (3:1 for icons) against every given background. - palette(): green/amber/red/accent/label are made readable against the window, the zebra row and the KPI card; Palette::text() guards every computed cell colour (ratio and temperature blends, firmware hues). - Media button icons: at least 3:1 against the theme's button face. - macOS snapshot (wx-rs patch 0011): capture the window's frame view. The content view alone left unpainted areas transparent, which read as a white toolbar strip in dark mode. On screen the area was always the dark window colour. After the change, no app-coloured text is below 4.5:1 in any of the six theme/platform combinations. What the checker still flags is theme chrome (grid lines, GTK header labels, button outlines, the zoom slider) and anti-aliasing on thin fonts. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BdKQBRg6YCM1XXQCTnD5GF --- crates/alkane-gui/src/ui.rs | 125 ++++++++++++++++-- .../patches/0011-macos-snapshot-frame.patch | 17 +++ thirdparty/wx-rs/patches/README.md | 1 + .../wx-rs-0.2.0-patched/cpp_src/osx_native.mm | 6 +- 4 files changed, 138 insertions(+), 11 deletions(-) create mode 100644 thirdparty/wx-rs/patches/0011-macos-snapshot-frame.patch diff --git a/crates/alkane-gui/src/ui.rs b/crates/alkane-gui/src/ui.rs index 674b69e6..0d04caac 100644 --- a/crates/alkane-gui/src/ui.rs +++ b/crates/alkane-gui/src/ui.rs @@ -176,6 +176,68 @@ struct Palette { accent: (u8, u8, u8), /// Odd-row (zebra) background: a subtle tint of the window colour. zebra: (u8, u8, u8), + /// Backgrounds coloured text is drawn on (window, zebra row, KPI card). + /// `text()` keeps every computed text colour readable on all of them. + text_bgs: Vec<(u8, u8, u8)>, +} + +/// WCAG relative luminance of an sRGB colour. +fn wcag_luminance(c: (u8, u8, u8)) -> f64 { + let ch = |v: u8| { + let v = v as f64 / 255.0; + if v <= 0.03928 { + v / 12.92 + } else { + ((v + 0.055) / 1.055).powf(2.4) + } + }; + 0.2126 * ch(c.0) + 0.7152 * ch(c.1) + 0.0722 * ch(c.2) +} + +/// WCAG contrast ratio of two colours (1.0 to 21.0). +fn contrast_ratio(a: (u8, u8, u8), b: (u8, u8, u8)) -> f64 { + let (la, lb) = (wcag_luminance(a), wcag_luminance(b)); + (la.max(lb) + 0.05) / (la.min(lb) + 0.05) +} + +/// Minimum contrast for text: WCAG AA for normal-size text. +const MIN_TEXT_CONTRAST: f64 = 4.5; +/// Minimum contrast for icons and other graphics (WCAG non-text contrast). +const MIN_ICON_CONTRAST: f64 = 3.0; + +/// `c`, darkened (on light backgrounds) or lightened (on dark ones) just +/// enough to reach MIN_TEXT_CONTRAST against every background in `bgs`, +/// keeping its hue. Colours that already pass are returned unchanged. +fn readable(c: (u8, u8, u8), bgs: &[(u8, u8, u8)]) -> (u8, u8, u8) { + readable_at(c, bgs, MIN_TEXT_CONTRAST) +} + +/// `readable` with an explicit minimum ratio (MIN_ICON_CONTRAST for icons). +fn readable_at(c: (u8, u8, u8), bgs: &[(u8, u8, u8)], min: f64) -> (u8, u8, u8) { + let passes = |c| bgs.iter().all(|&bg| contrast_ratio(c, bg) >= min); + if bgs.is_empty() || passes(c) { + return c; + } + let mean = bgs.iter().map(|&bg| wcag_luminance(bg)).sum::() / bgs.len() as f64; + let target = if mean > 0.18 { + (0, 0, 0) + } else { + (255, 255, 255) + }; + for step in 1..=50 { + let d = tint_toward(c, target, step as f64 / 50.0); + if passes(d) { + return d; + } + } + target +} + +impl Palette { + /// A text colour adjusted to stay readable on this theme's backgrounds. + fn text(&self, c: (u8, u8, u8)) -> (u8, u8, u8) { + readable(c, &self.text_bgs) + } } fn luminance(c: (u8, u8, u8)) -> f32 { @@ -212,11 +274,11 @@ fn tint_toward(base: (u8, u8, u8), target: (u8, u8, u8), f: f64) -> (u8, u8, u8) /// output reads as clearly bad, and 100% reads green. fn ratio_color(pal: &Palette, ratio: f64) -> (u8, u8, u8) { let t = ((ratio - 0.5) / 0.5).clamp(0.0, 1.0); - if t <= 0.5 { + pal.text(if t <= 0.5 { tint_toward(pal.red, pal.amber, t / 0.5) } else { tint_toward(pal.amber, pal.green, (t - 0.5) / 0.5) - } + }) } /// Whether a firmware family has a supported restore-to-stock path (round 12 @@ -252,11 +314,11 @@ fn firmware_color(family: &str) -> Option<(u8, u8, u8)> { /// Colour for a chip-temperature reading: cool blue at/below 40 C fading to hot /// red at/above 90 C, so a hot miner reads red at a glance. fn temp_color(pal: &Palette, temp_c: f64) -> (u8, u8, u8) { - tint_toward( + pal.text(tint_toward( pal.accent, pal.red, ((temp_c - 40.0) / 50.0).clamp(0.0, 1.0), - ) + )) } /// Build the segment-encoded cell for a combined actual/expected column @@ -624,7 +686,7 @@ fn palette() -> Palette { let win = wx_rs::system_color(0); // window background let text = wx_rs::system_color(1); // window text let dark = luminance(win) < 128.0; - Palette { + let mut p = Palette { // Cards read as slightly elevated vs the window: lighter in dark mode, // pure white on a light-grey window. card_bg: if dark { @@ -653,7 +715,17 @@ fn palette() -> Palette { } else { nudge(win, -10) }, - } + text_bgs: Vec::new(), + }; + // Every coloured text must read on the window, the zebra rows and the + // KPI cards in both themes; tune the fixed hues to those backgrounds. + p.text_bgs = vec![win, p.zebra, p.card_bg]; + p.label = p.text(p.label); + p.green = p.text(p.green); + p.amber = p.text(p.amber); + p.red = p.text(p.red); + p.accent = p.text(p.accent); + p } pub struct App { @@ -1018,11 +1090,15 @@ pub fn build(frame: Widget) -> App { ctl.add_spacer(8); // Play / pause / stop as coloured media icons (green / amber / red). Vivid // fixed colours read well on both light and dark themes. - let play_btn = Widget::media_button(panel, ID_PLAY, 0, (56, 190, 108)); + // The icon colours are kept to at least 3:1 against this theme's button + // face (the fixed hues alone were about 2:1 on light buttons). + let face = [wx_rs::system_color(3)]; + let icon = |c| readable_at(c, &face, MIN_ICON_CONTRAST); + let play_btn = Widget::media_button(panel, ID_PLAY, 0, icon((56, 190, 108))); ctl.add(play_btn, 0, sf::ALIGN_CENTRE_VERTICAL | sf::BORDER_ALL, 2); - let pause_btn = Widget::media_button(panel, ID_PAUSE, 1, (240, 172, 40)); + let pause_btn = Widget::media_button(panel, ID_PAUSE, 1, icon((240, 172, 40))); ctl.add(pause_btn, 0, sf::ALIGN_CENTRE_VERTICAL | sf::BORDER_ALL, 2); - let stop_btn = Widget::media_button(panel, ID_STOP, 2, (226, 72, 60)); + let stop_btn = Widget::media_button(panel, ID_STOP, 2, icon((226, 72, 60))); ctl.add(stop_btn, 0, sf::ALIGN_CENTRE_VERTICAL | sf::BORDER_ALL, 2); ctl.add_stretch(1); // Toolbar buttons; labels are localized and tracked for live re-labelling @@ -1440,7 +1516,10 @@ impl App { let color = (!r.errors.is_empty()).then_some(self.pal.red); encode_flag_cell(&c.cell(r), color) } - Column::Firmware => encode_flag_cell(&c.cell(r), firmware_color(&r.firmware)), + Column::Firmware => encode_flag_cell( + &c.cell(r), + firmware_color(&r.firmware).map(|fc| self.pal.text(fc)), + ), Column::Status => { // The status reads as its KPI icon (round 12 #11), drawn // in the status colour so it matches the dashboard card. @@ -5587,9 +5666,35 @@ mod tests { red: (255, 0, 0), accent: (0, 0, 255), zebra: (245, 245, 245), + text_bgs: Vec::new(), } } + #[test] + fn readable_reaches_aa_contrast_on_every_background() { + let light = [(255, 255, 255), (245, 245, 245)]; + let dark = [(30, 30, 30), (41, 41, 41), (44, 44, 44)]; + for fw in [ + "braiins", "luxos", "vnish", "bixbit", "epic", "hiveon", "alkane", + ] { + let c = firmware_color(fw).unwrap(); + for bgs in [&light[..], &dark[..]] { + let r = readable(c, bgs); + for &bg in bgs { + assert!( + contrast_ratio(r, bg) >= MIN_TEXT_CONTRAST, + "{fw} {r:?} on {bg:?}" + ); + } + } + } + // Already-readable colours are left alone; hue survives the nudge. + assert_eq!(readable((0, 0, 0), &light), (0, 0, 0)); + let gold = readable((185, 150, 20), &light); + assert!(gold.0 > gold.1 && gold.1 > gold.2, "still gold: {gold:?}"); + assert!((contrast_ratio((255, 255, 255), (0, 0, 0)) - 21.0).abs() < 0.01); + } + #[test] fn tint_toward_endpoints_and_midpoint() { let a = (10, 20, 30); diff --git a/thirdparty/wx-rs/patches/0011-macos-snapshot-frame.patch b/thirdparty/wx-rs/patches/0011-macos-snapshot-frame.patch new file mode 100644 index 00000000..fa72e66f --- /dev/null +++ b/thirdparty/wx-rs/patches/0011-macos-snapshot-frame.patch @@ -0,0 +1,17 @@ +Subject: [PATCH 0011] macOS self-test snapshot includes the window background + +--- a/cpp_src/osx_native.mm ++++ b/cpp_src/osx_native.mm +@@ -46,7 +46,11 @@ + wxMilliSleep(30); + } + NSWindow* nsw = (NSWindow*)tlw->GetWXWindow(); +- NSView* view = [nsw contentView]; ++ // The content view's superview (the window's frame view) also draws the ++ // window background and title bar. The content view alone leaves every ++ // area the app's panels do not paint transparent, which read as white. ++ NSView* view = [[nsw contentView] superview]; ++ if (!view) view = [nsw contentView]; + if (!view) return 0; + NSRect rect = [view bounds]; + NSBitmapImageRep* rep = [view bitmapImageRepForCachingDisplayInRect:rect]; diff --git a/thirdparty/wx-rs/patches/README.md b/thirdparty/wx-rs/patches/README.md index 9c2cf13a..59054590 100644 --- a/thirdparty/wx-rs/patches/README.md +++ b/thirdparty/wx-rs/patches/README.md @@ -29,6 +29,7 @@ later changes go in new patches. | 0008 | Widget bridge on wxMSW: generic data-view input and tooltips, DIP boundary, anti-aliased shapes, themed selection colours | | 0009 | macOS: wxOSX (universal static) through `wx-config`, logical sizes on Apple, clang compiler runtime for `@available` | | 0010 | macOS table: native alternating rows instead of the unclipped custom-cell background fill (it hid neighbouring cells' text), theme-aware text colour, `osx_native.mm`, self-test window snapshot | +| 0011 | macOS self-test snapshot captures the window's frame view, so areas the app does not paint show the real window background instead of transparency | History: the round 19 health-tooltip fix (GTK tip area converted from bin-window to widget coordinates) used to be a separate patch on top of an diff --git a/thirdparty/wx-rs/wx-rs-0.2.0-patched/cpp_src/osx_native.mm b/thirdparty/wx-rs/wx-rs-0.2.0-patched/cpp_src/osx_native.mm index cf8e3c62..f8867a50 100644 --- a/thirdparty/wx-rs/wx-rs-0.2.0-patched/cpp_src/osx_native.mm +++ b/thirdparty/wx-rs/wx-rs-0.2.0-patched/cpp_src/osx_native.mm @@ -46,7 +46,11 @@ int wxbr_osx_snapshot(void* win, const char* path) { wxMilliSleep(30); } NSWindow* nsw = (NSWindow*)tlw->GetWXWindow(); - NSView* view = [nsw contentView]; + // The content view's superview (the window's frame view) also draws the + // window background and title bar. The content view alone leaves every + // area the app's panels do not paint transparent, which read as white. + NSView* view = [[nsw contentView] superview]; + if (!view) view = [nsw contentView]; if (!view) return 0; NSRect rect = [view bounds]; NSBitmapImageRep* rep = [view bitmapImageRepForCachingDisplayInRect:rect]; -- 2.54.0