feat: style embedded figures as a card on dark pages

Move the dark-theme styling out of sphinx-gallery: sphinx-gallery should
not carry plotly-specific CSS, so ship a scoped style with each embed
(repr fallback and scraper) instead. The white padded card only shows on
dark pages (data-theme toggles or OS preference); on light pages it is
invisible.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: larsoner

plotly/basedatatypes.py

@@ -827,18 +827,19 @@ def _repr_html_(self):
         else:
             import uuid
 
-            from plotly.io._utils import resize_after_load_script
+            from plotly.io._utils import embed_in_output_card, resize_after_load_script
 
             div_id = str(uuid.uuid4())
             # Size like the html renderers do: "100%" height collapses or
             # overflows in plain-HTML consumers such as sphinx-gallery.
-            return self.to_html(
+            html = self.to_html(
                 full_html=False,
                 include_plotlyjs="cdn",
                 default_width="100%",
                 default_height=525,
                 div_id=div_id,
-            ) + resize_after_load_script(div_id)
+            )
+            return embed_in_output_card(html + resize_after_load_script(div_id))
 
     def _repr_mimebundle_(self, include=None, exclude=None, validate=True, **kwargs):
         """

plotly/io/_sg_scraper.py

@@ -11,7 +11,7 @@
 import plotly
 from plotly.basedatatypes import BaseFigure
 from plotly.io._base_renderers import sphinx_gallery_figures
-from plotly.io._utils import resize_after_load_script
+from plotly.io._utils import embed_in_output_card, resize_after_load_script
 
 plotly.io.renderers.default = "sphinx_gallery_png"
 
@@ -159,12 +159,12 @@ def _inline_html(fig_dict):
         validate=False,
         div_id=div_id,
     )
+    # The figure may draw before the page finishes laying out, ending up
+    # sized to a container whose width then changes.
+    html = embed_in_output_card(html + resize_after_load_script(div_id))
     html = (
         '<div class="output_subarea output_html rendered_html output_result">\n'
         f"{html}\n"
-        # The figure may draw before the page finishes laying out, ending up
-        # sized to a container whose width then changes.
-        f"{resize_after_load_script(div_id)}\n"
         "</div>"
     )
     return "\n.. raw:: html\n\n" + textwrap.indent(html, "    ") + "\n"

plotly/io/_utils.py

@@ -110,3 +110,24 @@ def resize_after_load_script(div_id):
         'else window.addEventListener("load", fit);'
         "})();</script>"
     )
+
+
+def embed_in_output_card(html):
+    """Wrap embedded-figure HTML in a card that stays legible on dark pages.
+
+    The figure keeps the light background baked into it, so on dark pages an
+    edge-to-edge white slab results; a white padded card reads as intentional
+    instead. Both dark selectors are needed: ``data-theme`` covers themes
+    with an explicit toggle, the media query covers theme-less pages under a
+    dark OS preference. On light pages the white-on-white card is invisible.
+    """
+    card = "background:#fff;border-radius:0.25rem;padding:0.5rem"
+    return (
+        "<style>"
+        f'html[data-theme="dark"] .plotly-output-card{{{card}}}'
+        "@media (prefers-color-scheme: dark){"
+        f'html:not([data-theme="light"]) .plotly-output-card{{{card}}}'
+        "}"
+        "</style>"
+        f'<div class="plotly-output-card">{html}</div>'
+    )

tests/test_io/test_sg_scraper.py

@@ -142,6 +142,8 @@ def test_scraper(gallery, image_format):
     assert rst.count('class="output_subarea') == 2
     # Fixes up figures drawn while the page was still laying out
     assert rst.count("Plotly.Plots.resize") == 2
+    # Styled as a card so the light-background figure works on dark pages
+    assert rst.count('class="plotly-output-card"') == 2
 
     # The thumbnail must be a scraped figure rather than a "no image" default,
     # and one image per figure in order is what makes `thumbnail_number` work
@@ -264,6 +266,8 @@ def test_repr_html_fallback_size(monkeypatch):
     assert 'style="height:525px; width:100%;"' in html
     # Fixes up figures drawn while the page was still laying out
     assert "Plotly.Plots.resize" in html
+    # Styled as a card so the light-background figure works on dark pages
+    assert 'class="plotly-output-card"' in html
     fig = go.Figure(layout={"height": 400})
     assert 'style="height:400px; width:100%;"' in fig._repr_html_()