Rework the 'Why UltraPlot?' page with before/after comparison cards

.gitignore

@@ -22,6 +22,7 @@ docs/_build
 docs/_static/ultraplotrc
 docs/_static/rctable.rst
 docs/_static/*
+!docs/_static/why_plots/
 *.html
 docs/gallery/
 docs/sg_execution_times.rst

docs/_static/custom.css

@@ -1250,3 +1250,213 @@ body.wy-body-for-nav
     max-width: 100%;
     height: auto;
 }
+
+/* Why UltraPlot page: before/after comparison cards */
+.uplt-why {
+    border: 1px solid var(--uplt-color-border-muted);
+    border-radius: 0.8rem;
+    background: linear-gradient(
+        180deg,
+        var(--uplt-color-white) 0%,
+        var(--uplt-color-sidebar-bg) 100%
+    );
+    box-shadow: 0 4px 14px var(--uplt-color-shadow);
+    overflow: hidden;
+}
+
+.uplt-why-mpl {
+    border-top: 4px solid #b45309;
+}
+
+.uplt-why-uplt {
+    border-top: 4px solid #178f84;
+}
+
+.uplt-why img {
+    width: 100%;
+    height: auto;
+    border-radius: 0.45rem;
+    background: var(--uplt-color-panel-bg);
+}
+
+.uplt-why-compare {
+    margin-bottom: 0.75rem;
+}
+
+.uplt-why-compare .sd-card-body {
+    padding: 0.75rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+}
+
+.uplt-why-compare .uplt-compare-labels {
+    display: flex;
+    justify-content: space-between;
+    gap: 0.6rem;
+    padding: 0.4rem 0.75rem 0;
+    font-weight: 700;
+    font-size: 0.85rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+}
+
+.uplt-why-compare .uplt-compare-labels .uplt-label {
+    background: var(--uplt-color-panel-bg);
+    border: 1px solid var(--uplt-color-border-muted);
+    border-radius: 9999px;
+    padding: 0.1rem 0.6rem;
+}
+
+.uplt-why-compare .uplt-compare-labels .uplt-label-mpl {
+    color: #b45309;
+}
+
+.uplt-why-compare .uplt-compare-labels .uplt-label-uplt {
+    color: #178f84;
+}
+
+.uplt-compare-frame {
+    position: relative;
+    width: 100%;
+    max-width: 100%;
+    overflow: hidden;
+    border-radius: 0.45rem;
+    border: 1px solid var(--uplt-color-border-muted);
+    background: var(--uplt-color-panel-bg);
+    --uplt-compare-position: 50%;
+}
+
+.uplt-compare-frame .uplt-compare-side {
+    position: relative;
+    width: 100%;
+    overflow: hidden;
+}
+
+.uplt-compare-frame .uplt-compare-side .sd-card-body {
+    margin: 0;
+    padding: 0.75rem;
+    color: inherit;
+}
+
+.uplt-compare-frame .uplt-compare-side .sd-card-body figure {
+    width: 100%;
+    margin: 0;
+}
+
+.uplt-compare-frame .uplt-compare-side .sd-card-body figure.align-default {
+    text-align: left;
+}
+
+.uplt-compare-frame .uplt-compare-side .sd-card-body figure img {
+    width: 100%;
+    height: auto;
+    display: block;
+    margin: 0;
+}
+
+.uplt-compare-frame .uplt-compare-side.uplt-compare-uplt {
+    position: relative;
+    z-index: 1;
+    clip-path: inset(0 0 0 var(--uplt-compare-position));
+}
+
+.uplt-compare-frame .uplt-compare-side.uplt-compare-mpl {
+    position: absolute;
+    inset: 0;
+    clip-path: inset(0 calc(100% - var(--uplt-compare-position)) 0 0);
+    z-index: 2;
+}
+
+.uplt-compare-frame .uplt-compare-handle {
+    position: absolute;
+    top: 0;
+    left: var(--uplt-compare-position);
+    transform: translateX(-50%);
+    width: 2px;
+    height: 100%;
+    background: var(--uplt-color-text-secondary);
+    opacity: 0.95;
+    pointer-events: none;
+    z-index: 3;
+}
+
+.uplt-compare-slider {
+    display: block;
+    width: 100%;
+}
+
+.uplt-compare-slider input[type="range"] {
+    width: 100%;
+    margin: 0;
+}
+
+.uplt-compare-label-btn {
+    appearance: none;
+    border: 1px solid var(--uplt-color-border-muted);
+    border-radius: 9999px;
+    background: var(--uplt-color-panel-bg);
+    color: inherit;
+    padding: 0.1rem 0.6rem;
+    margin: 0;
+    font: inherit;
+    font-weight: 700;
+    font-size: 0.85rem;
+    letter-spacing: 0.05em;
+    line-height: 1.2;
+    text-transform: uppercase;
+    cursor: pointer;
+}
+
+.uplt-compare-label-btn:focus-visible {
+    outline: 2px solid var(--uplt-color-accent);
+    outline-offset: 2px;
+}
+
+.uplt-compare-col {
+    grid-column: 1 / -1;
+}
+
+.uplt-why-compare-row {
+    align-items: stretch;
+}
+
+.uplt-why-compare-row .uplt-why-compare-col,
+.uplt-why-compare-row .uplt-why-compare-col.sd-col {
+    flex: 0 0 100% !important;
+    width: 100% !important;
+    max-width: 100% !important;
+    grid-column: 1 / -1;
+}
+
+.uplt-why-compare-row .uplt-why-compare-hide-col {
+    display: none !important;
+}
+
+
+.uplt-why .sd-card-body > p:first-child {
+    font-weight: 700;
+    font-size: 0.9rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+}
+
+.uplt-why-mpl .sd-card-body > p:first-child strong {
+    color: #b45309;
+}
+
+.uplt-why-uplt .sd-card-body > p:first-child strong {
+    color: #178f84;
+}
+
+.uplt-why .sd-card-body > p:last-child {
+    margin-top: auto;
+    padding-top: 0.35rem;
+    color: var(--uplt-color-text-secondary);
+}
+
+html.dark .uplt-why,
+html.dark-theme .uplt-why,
+[data-color-mode="dark"] .uplt-why {
+    background: linear-gradient(180deg, #252525 0%, #1f1f1f 100%);
+}

docs/_static/custom.js

@@ -38,6 +38,128 @@ function getCodeDetailsBlocks() {
   return Array.from(document.querySelectorAll("details.uplt-code-details"));
 }
 
+function initWhyCompareSliders() {
+  const isWhyPage = /\/why(?:\.html)?$|\/why\.htm$/.test(
+    (window.location.pathname || "").toLowerCase(),
+  );
+  if (!isWhyPage) return;
+
+  const cards = Array.from(document.querySelectorAll(".sd-card.uplt-why"));
+  for (let i = 0; i < cards.length - 1; i += 1) {
+    const mplCard = cards[i];
+    const upltCard = cards[i + 1];
+    if (
+      !mplCard ||
+      !upltCard ||
+      !mplCard.classList.contains("uplt-why-mpl") ||
+      !upltCard.classList.contains("uplt-why-uplt")
+    ) {
+      continue;
+    }
+    i += 1;
+
+    const mplBody = mplCard.querySelector(".sd-card-body");
+    const upltBody = upltCard.querySelector(".sd-card-body");
+    if (!mplBody || !upltBody) {
+      continue;
+    }
+
+    const slider = document.createElement("div");
+    slider.className = "uplt-why-compare";
+
+    const body = document.createElement("div");
+    body.className = "sd-card-body";
+    slider.appendChild(body);
+
+    const labels = document.createElement("div");
+    labels.className = "uplt-compare-labels";
+    const leftLabel = document.createElement("button");
+    leftLabel.type = "button";
+    leftLabel.className = "uplt-label uplt-label-mpl uplt-compare-label-btn";
+    leftLabel.textContent = "Matplotlib";
+    leftLabel.addEventListener("click", () => {
+      sliderInput.value = "100";
+      onInput();
+    });
+
+    const rightLabel = document.createElement("button");
+    rightLabel.type = "button";
+    rightLabel.className = "uplt-label uplt-label-uplt uplt-compare-label-btn";
+    rightLabel.textContent = "UltraPlot";
+    rightLabel.addEventListener("click", () => {
+      sliderInput.value = "0";
+      onInput();
+    });
+    labels.appendChild(leftLabel);
+    labels.appendChild(rightLabel);
+    body.appendChild(labels);
+
+    const frame = document.createElement("div");
+    frame.className = "uplt-compare-frame";
+    frame.setAttribute(
+      "aria-label",
+      "Matplotlib and UltraPlot before/after comparison",
+    );
+
+    const mplLayer = document.createElement("div");
+    mplLayer.className = "uplt-compare-side uplt-compare-mpl";
+    mplLayer.appendChild(mplBody.cloneNode(true));
+    frame.appendChild(mplLayer);
+
+    const upltLayer = document.createElement("div");
+    upltLayer.className = "uplt-compare-side uplt-compare-uplt";
+    upltLayer.appendChild(upltBody.cloneNode(true));
+    frame.appendChild(upltLayer);
+
+    const handle = document.createElement("div");
+    handle.className = "uplt-compare-handle";
+    frame.appendChild(handle);
+
+    const sliderInput = document.createElement("input");
+    sliderInput.className = "uplt-compare-slider";
+    sliderInput.type = "range";
+    sliderInput.min = "0";
+    sliderInput.max = "100";
+    sliderInput.value = "50";
+    sliderInput.setAttribute("aria-label", "Comparison reveal amount");
+
+    const onInput = () => {
+      frame.style.setProperty("--uplt-compare-position", `${sliderInput.value}%`);
+    };
+    sliderInput.addEventListener("input", onInput);
+    onInput();
+
+    body.appendChild(frame);
+    body.appendChild(sliderInput);
+
+    mplCard.className = "sd-card uplt-why uplt-why-compare";
+    mplCard.replaceChildren();
+    mplCard.appendChild(body);
+
+    const compareCol = mplCard.closest(".sd-col");
+    if (compareCol) {
+      compareCol.classList.add("uplt-why-compare-col");
+      compareCol.style.width = "100%";
+      compareCol.style.maxWidth = "100%";
+      compareCol.style.flex = "0 0 100%";
+    }
+
+    const compareRow = mplCard.closest(".sd-row");
+    if (compareRow) {
+      compareRow.classList.add("uplt-why-compare-row");
+      compareRow.style.display = "block";
+    }
+
+    const upltCol = upltCard.closest(".sd-col");
+    if (upltCol) {
+      upltCol.classList.add("uplt-why-compare-hide-col");
+      upltCol.style.display = "none";
+    }
+
+    upltCard.style.display = "none";
+  }
+}
+
 function initScrollChromeFade() {
   const topBar = document.querySelector(".sy-head");
   const leftBar = document.querySelector(".sy-lside");
@@ -711,6 +833,7 @@ document.addEventListener("DOMContentLoaded", function () {
 
   // Re-sync right TOC controls now that code wrappers exist.
   initShibuyaRightToc();
+  initWhyCompareSliders();
 
   const navLinks = document.querySelectorAll(
     ".wy-menu-vertical a.reference.internal",

docs/conf.py

@@ -427,6 +427,10 @@ def _reset_ultraplot(gallery_conf, fname):
     "}",
 ]
 
+# Prefer vector graphics for sphinx ``plot`` directives so plots stay sharp
+# without high-DPI raster scaling.
+plot_formats = ["svg"]
+
 # Control notebook execution from env for predictable local/CI builds.
 # Use values: auto, always, never.
 nbsphinx_execute = os.environ.get("UPLT_DOCS_EXECUTE", "auto").strip().lower()