feat: resolve #7 theme_civilytics(): default to a transparent background, opt-in for Civilytics cream

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)) +