1use gpui::Hsla;
2
3/// APCA (Accessible Perceptual Contrast Algorithm) constants
4/// Based on APCA 0.0.98G-4g W3 compatible constants
5/// https://github.com/Myndex/apca-w3
6struct APCAConstants {
7 // Main TRC exponent for monitor perception
8 main_trc: f32,
9
10 // sRGB coefficients
11 s_rco: f32,
12 s_gco: f32,
13 s_bco: f32,
14
15 // G-4g constants for use with 2.4 exponent
16 norm_bg: f32,
17 norm_txt: f32,
18 rev_txt: f32,
19 rev_bg: f32,
20
21 // G-4g Clamps and Scalers
22 blk_thrs: f32,
23 blk_clmp: f32,
24 scale_bow: f32,
25 scale_wob: f32,
26 lo_bow_offset: f32,
27 lo_wob_offset: f32,
28 delta_y_min: f32,
29 lo_clip: f32,
30}
31
32impl Default for APCAConstants {
33 fn default() -> Self {
34 Self {
35 main_trc: 2.4,
36 s_rco: 0.2126729,
37 s_gco: 0.7151522,
38 s_bco: 0.0721750,
39 norm_bg: 0.56,
40 norm_txt: 0.57,
41 rev_txt: 0.62,
42 rev_bg: 0.65,
43 blk_thrs: 0.022,
44 blk_clmp: 1.414,
45 scale_bow: 1.14,
46 scale_wob: 1.14,
47 lo_bow_offset: 0.027,
48 lo_wob_offset: 0.027,
49 delta_y_min: 0.0005,
50 lo_clip: 0.1,
51 }
52 }
53}
54
55/// Calculates the perceptual lightness contrast using APCA.
56/// Returns a value between approximately -108 and 106.
57/// Negative values indicate light text on dark background.
58/// Positive values indicate dark text on light background.
59///
60/// The APCA algorithm is more perceptually accurate than WCAG 2.x,
61/// especially for dark mode interfaces. Key improvements include:
62/// - Better accuracy for dark backgrounds
63/// - Polarity-aware (direction matters)
64/// - Perceptually uniform across the range
65///
66/// Common APCA Lc thresholds per ARC Bronze Simple Mode:
67/// https://readtech.org/ARC/tests/bronze-simple-mode/
68/// - Lc 45: Minimum for large fluent text (36px+)
69/// - Lc 60: Minimum for other content text
70/// - Lc 75: Minimum for body text
71/// - Lc 90: Preferred for body text
72///
73/// Most terminal themes use colors with APCA values of 40-70.
74///
75/// https://github.com/Myndex/apca-w3
76pub fn apca_contrast(text_color: Hsla, background_color: Hsla) -> f32 {
77 let constants = APCAConstants::default();
78
79 let text_y = srgb_to_y(text_color, &constants);
80 let bg_y = srgb_to_y(background_color, &constants);
81
82 // Apply soft clamp to near-black colors
83 let text_y_clamped = if text_y > constants.blk_thrs {
84 text_y
85 } else {
86 text_y + (constants.blk_thrs - text_y).powf(constants.blk_clmp)
87 };
88
89 let bg_y_clamped = if bg_y > constants.blk_thrs {
90 bg_y
91 } else {
92 bg_y + (constants.blk_thrs - bg_y).powf(constants.blk_clmp)
93 };
94
95 // Return 0 for extremely low delta Y
96 if (bg_y_clamped - text_y_clamped).abs() < constants.delta_y_min {
97 return 0.0;
98 }
99
100 let sapc;
101 let output_contrast;
102
103 if bg_y_clamped > text_y_clamped {
104 // Normal polarity: dark text on light background
105 sapc = (bg_y_clamped.powf(constants.norm_bg) - text_y_clamped.powf(constants.norm_txt))
106 * constants.scale_bow;
107
108 // Low contrast smooth rollout to prevent polarity reversal
109 output_contrast = if sapc < constants.lo_clip {
110 0.0
111 } else {
112 sapc - constants.lo_bow_offset
113 };
114 } else {
115 // Reverse polarity: light text on dark background
116 sapc = (bg_y_clamped.powf(constants.rev_bg) - text_y_clamped.powf(constants.rev_txt))
117 * constants.scale_wob;
118
119 output_contrast = if sapc > -constants.lo_clip {
120 0.0
121 } else {
122 sapc + constants.lo_wob_offset
123 };
124 }
125
126 // Return Lc (lightness contrast) scaled to percentage
127 output_contrast * 100.0
128}
129
130/// Converts sRGB color to Y (luminance) for APCA calculation
131fn srgb_to_y(color: Hsla, constants: &APCAConstants) -> f32 {
132 let rgba = color.to_rgb();
133
134 // Linearize and apply coefficients
135 let r_linear = (rgba.r).powf(constants.main_trc);
136 let g_linear = (rgba.g).powf(constants.main_trc);
137 let b_linear = (rgba.b).powf(constants.main_trc);
138
139 constants.s_rco * r_linear + constants.s_gco * g_linear + constants.s_bco * b_linear
140}
141
142/// Adjusts the foreground color to meet the minimum APCA contrast against the background.
143/// The minimum_apca_contrast should be an absolute value (e.g., 75 for Lc 75).
144///
145/// This implementation gradually adjusts the lightness while preserving the hue and
146/// saturation as much as possible, only falling back to black/white when necessary.
147pub fn ensure_minimum_contrast(
148 foreground: Hsla,
149 background: Hsla,
150 minimum_apca_contrast: f32,
151) -> Hsla {
152 if minimum_apca_contrast <= 0.0 {
153 return foreground;
154 }
155
156 let current_contrast = apca_contrast(foreground, background).abs();
157
158 if current_contrast >= minimum_apca_contrast {
159 return foreground;
160 }
161
162 // First, try to adjust lightness while preserving hue and saturation
163 let adjusted = adjust_lightness_for_contrast(foreground, background, minimum_apca_contrast);
164
165 let adjusted_contrast = apca_contrast(adjusted, background).abs();
166 if adjusted_contrast >= minimum_apca_contrast {
167 return adjusted;
168 }
169
170 // If that's not enough, gradually reduce saturation while adjusting lightness
171 let desaturated =
172 adjust_lightness_and_saturation_for_contrast(foreground, background, minimum_apca_contrast);
173
174 let desaturated_contrast = apca_contrast(desaturated, background).abs();
175 if desaturated_contrast >= minimum_apca_contrast {
176 return desaturated;
177 }
178
179 // Last resort: use black or white
180 let black = Hsla {
181 h: 0.0,
182 s: 0.0,
183 l: 0.0,
184 a: foreground.a,
185 };
186
187 let white = Hsla {
188 h: 0.0,
189 s: 0.0,
190 l: 1.0,
191 a: foreground.a,
192 };
193
194 let black_contrast = apca_contrast(black, background).abs();
195 let white_contrast = apca_contrast(white, background).abs();
196
197 if white_contrast > black_contrast {
198 white
199 } else {
200 black
201 }
202}
203
204/// Adjusts only the lightness to meet the minimum contrast, preserving hue and saturation
205fn adjust_lightness_for_contrast(
206 foreground: Hsla,
207 background: Hsla,
208 minimum_apca_contrast: f32,
209) -> Hsla {
210 // Determine if we need to go lighter or darker
211 let bg_luminance = srgb_to_y(background, &APCAConstants::default());
212 let should_go_darker = bg_luminance > 0.5;
213
214 // Binary search for the optimal lightness
215 let mut low = if should_go_darker { 0.0 } else { foreground.l };
216 let mut high = if should_go_darker { foreground.l } else { 1.0 };
217 let mut best_l = foreground.l;
218
219 for _ in 0..20 {
220 let mid = (low + high) / 2.0;
221 let test_color = Hsla {
222 h: foreground.h,
223 s: foreground.s,
224 l: mid,
225 a: foreground.a,
226 };
227
228 let contrast = apca_contrast(test_color, background).abs();
229
230 if contrast >= minimum_apca_contrast {
231 best_l = mid;
232 // Try to get closer to the minimum
233 if should_go_darker {
234 low = mid;
235 } else {
236 high = mid;
237 }
238 } else {
239 if should_go_darker {
240 high = mid;
241 } else {
242 low = mid;
243 }
244 }
245
246 // If we're close enough to the target, stop
247 if (contrast - minimum_apca_contrast).abs() < 1.0 {
248 best_l = mid;
249 break;
250 }
251 }
252
253 Hsla {
254 h: foreground.h,
255 s: foreground.s,
256 l: best_l,
257 a: foreground.a,
258 }
259}
260
261/// Adjusts both lightness and saturation to meet the minimum contrast
262fn adjust_lightness_and_saturation_for_contrast(
263 foreground: Hsla,
264 background: Hsla,
265 minimum_apca_contrast: f32,
266) -> Hsla {
267 // Try different saturation levels
268 let saturation_steps = [1.0, 0.8, 0.6, 0.4, 0.2, 0.0];
269
270 for &sat_multiplier in &saturation_steps {
271 let test_color = Hsla {
272 h: foreground.h,
273 s: foreground.s * sat_multiplier,
274 l: foreground.l,
275 a: foreground.a,
276 };
277
278 let adjusted = adjust_lightness_for_contrast(test_color, background, minimum_apca_contrast);
279 let contrast = apca_contrast(adjusted, background).abs();
280
281 if contrast >= minimum_apca_contrast {
282 return adjusted;
283 }
284 }
285
286 // If we get here, even grayscale didn't work, so return the grayscale attempt
287 Hsla {
288 h: foreground.h,
289 s: 0.0,
290 l: foreground.l,
291 a: foreground.a,
292 }
293}
294
295#[cfg(test)]
296mod tests {
297 use super::*;
298
299 fn hsla(h: f32, s: f32, l: f32, a: f32) -> Hsla {
300 Hsla { h, s, l, a }
301 }
302
303 fn hsla_from_hex(hex: u32) -> Hsla {
304 let r = ((hex >> 16) & 0xFF) as f32 / 255.0;
305 let g = ((hex >> 8) & 0xFF) as f32 / 255.0;
306 let b = (hex & 0xFF) as f32 / 255.0;
307
308 let max = r.max(g).max(b);
309 let min = r.min(g).min(b);
310 let l = (max + min) / 2.0;
311
312 if max == min {
313 // Achromatic
314 Hsla {
315 h: 0.0,
316 s: 0.0,
317 l,
318 a: 1.0,
319 }
320 } else {
321 let d = max - min;
322 let s = if l > 0.5 {
323 d / (2.0 - max - min)
324 } else {
325 d / (max + min)
326 };
327
328 let h = if max == r {
329 (g - b) / d + if g < b { 6.0 } else { 0.0 }
330 } else if max == g {
331 (b - r) / d + 2.0
332 } else {
333 (r - g) / d + 4.0
334 } / 6.0;
335
336 Hsla { h, s, l, a: 1.0 }
337 }
338 }
339
340 #[test]
341 fn test_apca_contrast() {
342 // Test black text on white background (should be positive)
343 let black = hsla(0.0, 0.0, 0.0, 1.0);
344 let white = hsla(0.0, 0.0, 1.0, 1.0);
345 let contrast = apca_contrast(black, white);
346 assert!(
347 contrast > 100.0,
348 "Black on white should have high positive contrast, got {}",
349 contrast
350 );
351
352 // Test white text on black background (should be negative)
353 let contrast_reversed = apca_contrast(white, black);
354 assert!(
355 contrast_reversed < -100.0,
356 "White on black should have high negative contrast, got {}",
357 contrast_reversed
358 );
359
360 // Same color should have zero contrast
361 let gray = hsla(0.0, 0.0, 0.5, 1.0);
362 let contrast_same = apca_contrast(gray, gray);
363 assert!(
364 contrast_same.abs() < 1.0,
365 "Same color should have near-zero contrast, got {}",
366 contrast_same
367 );
368
369 // APCA is NOT commutative - polarity matters
370 assert!(
371 (contrast + contrast_reversed).abs() > 1.0,
372 "APCA should not be commutative"
373 );
374 }
375
376 #[test]
377 fn test_srgb_to_y() {
378 let constants = APCAConstants::default();
379
380 // Test known Y values
381 let black = hsla(0.0, 0.0, 0.0, 1.0);
382 let y_black = srgb_to_y(black, &constants);
383 assert!(
384 y_black.abs() < 0.001,
385 "Black should have Y near 0, got {}",
386 y_black
387 );
388
389 let white = hsla(0.0, 0.0, 1.0, 1.0);
390 let y_white = srgb_to_y(white, &constants);
391 assert!(
392 (y_white - 1.0).abs() < 0.001,
393 "White should have Y near 1, got {}",
394 y_white
395 );
396 }
397
398 #[test]
399 fn test_ensure_minimum_contrast() {
400 let white_bg = hsla(0.0, 0.0, 1.0, 1.0);
401 let light_gray = hsla(0.0, 0.0, 0.9, 1.0);
402
403 // Light gray on white has poor contrast
404 let initial_contrast = apca_contrast(light_gray, white_bg).abs();
405 assert!(
406 initial_contrast < 15.0,
407 "Initial contrast should be low, got {}",
408 initial_contrast
409 );
410
411 // Should be adjusted to black for better contrast (using APCA Lc 45 as minimum)
412 let adjusted = ensure_minimum_contrast(light_gray, white_bg, 45.0);
413 assert_eq!(adjusted.l, 0.0); // Should be black
414 assert_eq!(adjusted.a, light_gray.a); // Alpha preserved
415
416 // Test with dark background
417 let black_bg = hsla(0.0, 0.0, 0.0, 1.0);
418 let dark_gray = hsla(0.0, 0.0, 0.1, 1.0);
419
420 // Dark gray on black has poor contrast
421 let initial_contrast = apca_contrast(dark_gray, black_bg).abs();
422 assert!(
423 initial_contrast < 15.0,
424 "Initial contrast should be low, got {}",
425 initial_contrast
426 );
427
428 // Should be adjusted to white for better contrast
429 let adjusted = ensure_minimum_contrast(dark_gray, black_bg, 45.0);
430 assert_eq!(adjusted.l, 1.0); // Should be white
431
432 // Test when contrast is already sufficient
433 let black = hsla(0.0, 0.0, 0.0, 1.0);
434 let adjusted = ensure_minimum_contrast(black, white_bg, 45.0);
435 assert_eq!(adjusted, black); // Should remain unchanged
436 }
437
438 #[test]
439 fn test_one_light_theme_exact_colors() {
440 // Test with exact colors from One Light theme
441 // terminal.background and terminal.ansi.white are both #fafafaff
442 let fafafa = hsla_from_hex(0xfafafa);
443
444 // They should be identical
445 let bg = fafafa;
446 let fg = fafafa;
447
448 // Contrast should be 0 (no contrast)
449 let contrast = apca_contrast(fg, bg);
450 assert!(
451 contrast.abs() < 1.0,
452 "Same color should have near-zero APCA contrast, got {}",
453 contrast
454 );
455
456 // With minimum APCA contrast of 15 (very low, but detectable), it should adjust
457 let adjusted = ensure_minimum_contrast(fg, bg, 15.0);
458 // The new algorithm preserves colors, so we just need to check contrast
459 let new_contrast = apca_contrast(adjusted, bg).abs();
460 assert!(
461 new_contrast >= 15.0,
462 "Adjusted contrast {} should be >= 15.0",
463 new_contrast
464 );
465
466 // The adjusted color should have sufficient contrast
467 let new_contrast = apca_contrast(adjusted, bg).abs();
468 assert!(
469 new_contrast >= 15.0,
470 "Adjusted APCA contrast {} should be >= 15.0",
471 new_contrast
472 );
473 }
474}