From e256b73053266d9f56e8bcec2989329e135fb697 Mon Sep 17 00:00:00 2001
From: kodor <kodor@civilytics.org>
Date: Sun, 21 Jun 2026 03:13:56 +0000
Subject: [PATCH] feat: resolve #7 theme_civilytics(): default to a transparent
 background, opt-in for Civilytics cream

---
 R/theme.R                   | 27 +++++++++++++++++++--------
 man/theme_civilytics.Rd     | 28 ++++++++++++++++++++--------
 tests/testthat/test_theme.R |  7 ++++++-
 3 files changed, 45 insertions(+), 17 deletions(-)

diff --git a/R/theme.R b/R/theme.R
index 503e5ac..e817813 100644
--- a/R/theme.R
+++ b/R/theme.R
@@ -36,10 +36,9 @@
 #'   to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).
 #' @param grid Character. Which major gridlines to draw: `"y"` (default,
 #'   horizontal only), `"x"` (vertical only), `"both"`, or `"none"`.
-#' @param paper_bg Logical. If `TRUE` (default), fill the plot and panel
-#'   backgrounds with the warm `paper` color. Set to `FALSE` for a
-#'   transparent background (useful for slides or overlay on colored
-#'   surfaces).
+#' @param paper_bg Logical. If `FALSE` (default), the plot and panel
+#'   backgrounds are transparent (`fill = NA`). Set to `TRUE` to fill them
+#'   with the warm `paper` color for a branded cream canvas.
 #'
 #' @section Font size hierarchy:
 #' All text sizes are derived from `font_size` using relative scale factors.
@@ -64,11 +63,23 @@
 #' @return A complete ggplot2 [ggplot2::theme()] object.
 #' @export
 #'
+#' @section Transparent device background:
+#' Setting `paper_bg = FALSE` makes the theme's `plot.background` and
+#' `panel.background` transparent (`fill = NA`), but the graphics device
+#' itself may still paint a solid background. To produce fully transparent
+#' PNGs, also pass a transparent device background:
+#'
+#' ```r
+#' ragg::agg_png("plot.png", background = "transparent")
+#' print(p)
+#' dev.off()
+#' ```
+#'
 #' @examples
 #' \dontrun{
 #' library(ggplot2)
 #'
-#' # Default editorial theme
+#' # Default: transparent background
 #' ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point() +
 #'   theme_civilytics()
@@ -79,10 +90,10 @@
 #'   scale_color_civilytics() +
 #'   theme_civilytics(grid = "both")
 #'
-#' # Transparent background for embedding
+#' # Branded cream canvas (opt-in)
 #' ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point() +
-#'   theme_civilytics(paper_bg = FALSE)
+#'   theme_civilytics(paper_bg = TRUE)
 #'
 #' # Larger text for poster or display
 #' ggplot(mpg, aes(displ, hwy)) +
@@ -102,7 +113,7 @@ theme_civilytics <- function(
     accent       = unname(civilytics_colors["ember_600"]),
     strip_color  = unname(civilytics_colors["paper_2"]),
     grid         = c("y", "x", "both", "none"),
-    paper_bg     = TRUE) {
+    paper_bg     = FALSE) {
 
   grid <- match.arg(grid)
   half_line  <- font_size / 2
diff --git a/man/theme_civilytics.Rd b/man/theme_civilytics.Rd
index c7dfeb4..bb75442 100644
--- a/man/theme_civilytics.Rd
+++ b/man/theme_civilytics.Rd
@@ -17,7 +17,7 @@ theme_civilytics(
   accent = unname(civilytics_colors["ember_600"]),
   strip_color = unname(civilytics_colors["paper_2"]),
   grid = c("y", "x", "both", "none"),
-  paper_bg = TRUE
+   paper_bg = FALSE
 )
 }
 \arguments{
@@ -56,10 +56,9 @@ to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).}
 \item{grid}{Character. Which major gridlines to draw: `"y"` (default,
 horizontal only), `"x"` (vertical only), `"both"`, or `"none"`.}
 
-\item{paper_bg}{Logical. If `TRUE` (default), fill the plot and panel
-backgrounds with the warm `paper` color. Set to `FALSE` for a
-transparent background (useful for slides or overlay on colored
-surfaces).}
+\item{paper_bg}{Logical. If `FALSE` (default), the plot and panel
+backgrounds are transparent (`fill = NA`). Set to `TRUE` to fill them
+with the warm `paper` color for a branded cream canvas.}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
@@ -101,11 +100,24 @@ logo below the plot, pass `font_scale` to compensate for viewport
 shrinkage.
 }
 
+\section{Transparent device background}{
+Setting `paper_bg = FALSE` makes the theme's `plot.background` and
+`panel.background` transparent (`fill = NA`), but the graphics device
+itself may still paint a solid background. To produce fully transparent
+PNGs, also pass a transparent device background:
+
+\if{html}{\out{<div class="sourceCode r">}}
+\preformatted{ragg::agg_png("plot.png", background = "transparent")
+print(p)
+dev.off()}
+\if{html}{\out{</div>}}
+}
+
 \examples{
 \dontrun{
 library(ggplot2)
 
-# Default editorial theme
+# Default: transparent background
 ggplot(mpg, aes(displ, hwy)) +
   geom_point() +
   theme_civilytics()
@@ -116,10 +128,10 @@ ggplot(mpg, aes(displ, hwy, colour = class)) +
   scale_color_civilytics() +
   theme_civilytics(grid = "both")
 
-# Transparent background for embedding
+# Branded cream canvas (opt-in)
 ggplot(mpg, aes(displ, hwy)) +
   geom_point() +
-  theme_civilytics(paper_bg = FALSE)
+  theme_civilytics(paper_bg = TRUE)
 
 # Larger text for poster or display
 ggplot(mpg, aes(displ, hwy)) +
diff --git a/tests/testthat/test_theme.R b/tests/testthat/test_theme.R
index 720f8a7..cafc89a 100644
--- a/tests/testthat/test_theme.R
+++ b/tests/testthat/test_theme.R
@@ -133,8 +133,13 @@ test_that("theme_civilytics uses brand ink color for text", {
   expect_equal(th$text$colour, unname(civilytics_colors["ink"]))
 })
 
-test_that("theme_civilytics uses brand paper color for plot background", {
+test_that("theme_civilytics defaults to transparent plot background", {
   th <- theme_civilytics()
+  expect_true(is.na(th$plot.background$fill))
+})
+
+test_that("theme_civilytics paper_bg=TRUE opt-in gives cream background", {
+  th <- theme_civilytics(paper_bg = TRUE)
   expect_equal(th$plot.background$fill, unname(civilytics_colors["paper"]))
 })