add css helper for images optimized for both dark and light theme

docs/user_guide/light-dark.rst

@@ -71,8 +71,8 @@ For example to define a different background color for both the light and dark t
 
 A complete list of the colors used in this theme can be found in the :doc:`CSS style section <styling>`.
 
-Use theme-dependent content
----------------------------
+Theme-dependent images and content
+----------------------------------
 
 It is possible to use different content for light and dark mode, so that the content only shows up when a particular theme is active.
 This is useful if your content depends on the theme's style, such as a PNG image with a light or a dark background.
@@ -100,6 +100,33 @@ Change the theme and a new image should be displayed.
 .. image:: https://source.unsplash.com/200x200/daily?cute+dog
     :class: only-light
 
+Images and content that work in both themes
+-------------------------------------------
+
+For images without the :code:`only-dark` class, when the **dark theme** is activated, a white background will automatically be added to ensure the image contents are visible.
+If your image is suitable for both light and dark theme, add the CSS class :code:`dark-light` to make your image theme-agnostic.
+
+For example, here's an image without adding this helper class.
+Change to the dark theme and a grey background will be present.
+
+.. code-block:: rst
+
+    .. image:: https://source.unsplash.com/200x200/daily?cute+cat
+        :class: p-2
+
+.. image:: https://source.unsplash.com/200x200/daily?cute+cat
+    :class: p-2
+
+Here's the same image with this class added:
+
+.. code-block:: rst
+
+    .. image:: https://source.unsplash.com/200x200/daily?cute+cat
+        :class: dark-light p-2
+
+.. image:: https://source.unsplash.com/200x200/daily?cute+cat
+    :class: dark-light p-2
+
 Define custom JavaScript to react to theme changes
 --------------------------------------------------
 

src/pydata_sphinx_theme/assets/styles/variables/_color.scss

@@ -108,10 +108,10 @@ $pst-semantic-colors: (
         filter: brightness(0.8) contrast(1.2);
       }
       /* Give images a light background in dark mode in case they have
-      *  transparency and black text (unless they have class .only-dark, in
+      *  transparency and black text (unless they have class .only-dark or .dark-light, in
       *  which case assume they're already optimized for dark mode).
       */
-      .bd-content img:not(.only-dark) {
+      .bd-content img:not(.only-dark):not(.dark-light) {
         background: rgb(255, 255, 255);
         border-radius: 0.25rem;
       }