From d09327581e7f1228026c55aceeebbe41548bc3f6 Mon Sep 17 00:00:00 2001 From: arne314 <73391160+arne314@users.noreply.github.com> Date: Thu, 13 Mar 2025 15:10:11 +0100 Subject: [PATCH] docs: add min contrast ratio --- kitty/options/definition.py | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/kitty/options/definition.py b/kitty/options/definition.py index eeb8ea77b..624c4f814 100644 --- a/kitty/options/definition.py +++ b/kitty/options/definition.py @@ -266,20 +266,30 @@ ''') opt('text_fg_override_threshold', 0, option_type='float', long_text=''' -The minimum accepted difference in luminance between the foreground and background +A setting to prevent low contrast scenarios, configurable in two different modes (positive and negative value). +The default value is :code:`0`, which means no overriding is performed. Useful when working with applications +that use colors that do not contrast well with your preferred color scheme. + +A positive value represents the minimum accepted difference in luminance between the foreground and background color, below which kitty will override the foreground color. It is percentage ranging from :code:`0` to :code:`100`. If the difference in luminance of the foreground and background is below this threshold, the foreground color will be set -to white if the background is dark or black if the background is light. The default -value is :code:`0`, which means no overriding is performed. Useful when working with applications -that use colors that do not contrast well with your preferred color scheme. +to white if the background is dark or black if the background is light. + +A negative value represents the minimum accepted contrast ratio between the foreground and background color. +Possible values range from :code:`-0.0` to :code:`-21.0`. +To for example meet :link:`WCAG level AA ` +a value of :code:`-4.5` can be provided. +The algorithm is implemented using :link:`HSLuv ` which enables it to change +the perceived lightness of a color just as much as needed without really changing its hue and saturation. WARNING: Some programs use characters (such as block characters) for graphics display and may expect to be able to set the foreground and background to the same color (or similar colors). If you see unexpected stripes, dots, lines, incorrect color, no color where you expect color, or any kind of graphic display problem try setting :opt:`text_fg_override_threshold` to :code:`0` to -see if this is the cause of the problem. +see if this is the cause of the problem or consider the minimum contrast ratio (negative value) +over the minimum difference as it implements a basic workaround for this scenario. ''') egr() # }}}