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

---
 R/theme.R                   | 20 +++++++++++---------
 tests/testthat/test_theme.R |  9 ++++++++-
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/R/theme.R b/R/theme.R
index 503e5ac..b9e5fd6 100644
--- a/R/theme.R
+++ b/R/theme.R
@@ -29,17 +29,19 @@
 #' @param ink Character. Hex code for foreground/text color. Defaults to
 #'   [civilytics_colors]`["ink"]` (`#0E1A2B`).
 #' @param paper Character. Hex code for background color. Defaults to
-#'   [civilytics_colors]`["paper"]` (`#FAF7F2`).
+#'   [civilytics_colors]`["paper"]` (`#FAF7F2`). Only used when
+#'   `paper_bg = TRUE`.
 #' @param accent Character. Hex code for accent/highlight color. Defaults to
 #'   [civilytics_colors]`["ember_600"]` (`#C25311`).
 #' @param strip_color Character. Hex code for facet strip background. Defaults
 #'   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 `TRUE`, fill the plot and panel
+#'   backgrounds with the warm `paper` color. Default `FALSE` for a
+#'   transparent background (recommended for embedding figures on
+#'   colored surfaces, slides, or report pages). Set to `TRUE` to
+#'   enable the branded cream canvas.
 #'
 #' @section Font size hierarchy:
 #' All text sizes are derived from `font_size` using relative scale factors.
@@ -68,7 +70,7 @@
 #' \dontrun{
 #' library(ggplot2)
 #'
-#' # Default editorial theme
+#' # Default transparent background
 #' ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point() +
 #'   theme_civilytics()
@@ -79,10 +81,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 +104,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/tests/testthat/test_theme.R b/tests/testthat/test_theme.R
index 720f8a7..6abd6ca 100644
--- a/tests/testthat/test_theme.R
+++ b/tests/testthat/test_theme.R
@@ -133,9 +133,16 @@ 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))
+  expect_true(is.na(th$panel.background$fill))
+})
+
+test_that("theme_civilytics paper_bg=TRUE restores cream background", {
+  th <- theme_civilytics(paper_bg = TRUE)
   expect_equal(th$plot.background$fill, unname(civilytics_colors["paper"]))
+  expect_equal(th$panel.background$fill, unname(civilytics_colors["paper"]))
 })
 
 test_that("theme_civilytics uses paper_2 for strip background by default", {