Document how to setup kitty for automatic OS color following

docs/changelog.rst

@@ -87,6 +87,8 @@ Detailed list of changes
 0.37.1 [future]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+- Allow :ref:`specifying individual color themes <auto_color_scheme>` to use so that kitty changes colors automatically following the OS dark/light mode
+
 - Discard OSC 9 notifications that start with :code:`4;` because some misguided software is using it for "progress reporting" (:iss:`8011`)
 
 0.37.0 [2024-10-30]

docs/kittens/themes.rst

@@ -47,11 +47,35 @@ Once that's done, the kitten sends kitty a signal to make it reload its config.
 
    If you want to have some color settings in your :file:`kitty.conf` that the
    theme kitten does not override, move them into a separate conf file and
-   ``include`` it into kitty.conf. The include should be places after the
+   ``include`` it into kitty.conf. The include should be placed after the
    inclusion of :file:`current-theme.conf` so that the settings in it override
    conflicting settings from :file:`current-theme.conf`.
 
 
+.. _auto_color_scheme:
+
+Change color themes automatically when the OS switches between light and dark
+--------------------------------------------------------------------------------
+
+You can have kitty automatically change its color theme when the OS switches
+between dark, light and no-preference modes. In order to do this, run the theme
+kitten as normal and at the final screen select the option to save your chosen
+theme as either light, dark, or no-preference. Repeat until you have chosen
+a theme for each of the three modes. Then, once you restart kitty, it will
+automatically use your chosen themes depending on the OS color scheme.
+
+This works by creating three files: :file:`dark-theme.auto.conf`,
+:file:`light-theme.auto.conf` and :file:`no-preference-theme.auto.conf` in the
+kitty config directory. When these files exist, kitty queries the OS for its color scheme
+and uses the appropriate file. Note that the colors in these files override all other
+colors, even those specified using the :option:`kitty --override` command line flag.
+kitty will also automatically change colors when the OS color scheme changes,
+for example, during night/day transitions.
+
+When using these colors, you can still dynamically change colors, but the next
+time the OS changes its color mode, any dynamics changes will be overridden.
+
+
 Using your own themes
 -----------------------
 

kitty/debug_config.py

@@ -17,8 +17,9 @@
 
 from .child import cmdline_of_pid
 from .cli import version
+from .colors import theme_colors
 from .constants import extensions_dir, is_macos, is_wayland, kitty_base_dir, kitty_exe, shell_path
-from .fast_data_types import Color, SingleKey, current_fonts, num_users, opengl_version_string, wayland_compositor_data
+from .fast_data_types import Color, SingleKey, current_fonts, glfw_get_system_color_theme, num_users, opengl_version_string, wayland_compositor_data
 from .options.types import Options as KittyOpts
 from .options.types import defaults
 from .options.utils import KeyboardMode, KeyDefinition
@@ -275,6 +276,7 @@ def debug_config(opts: KittyOpts, global_shortcuts: dict[str, SingleKey] | None
     p(yellow('  base dir:'), kitty_base_dir)
     p(yellow('  extensions dir:'), extensions_dir)
     p(yellow('  system shell:'), shell_path)
+    p(f'System color scheme: {green(glfw_get_system_color_theme())}. Applied color theme type: {yellow(theme_colors.applied_theme or "none")}')
     if opts.config_paths:
         p(green('Loaded config files:'))
         p(' ', '\n  '.join(opts.config_paths))