feat: expand color system to 53 colors/10 palettes, add grid/slide themes, and README gallery

Replace the 16-color / 3-palette system with the full Civilytics design
system: 53 named colors (full navy, ember, violet ramps plus teal, plum,
moss, brass supporting hues) and 10 visualization palettes (qual,
qual_warm, qual_cool, seq_ember, seq_navy, seq_violet, seq_paper_ink,
div_navy_ember, div_violet_ember).

Enrich theme_civilytics() with grid and paper_bg parameters, add
theme_civilytics_slide() for presentations, and load all four brand fonts
(Inter, Libre Franklin, Source Serif 4, JetBrains Mono).

Add README.Rmd with rendered gallery showing all palettes, theme
variants, grid options, dark/slide modes, facets, and scale usage.

man/civilytics-package.Rd

@@ -4,10 +4,32 @@
 \name{civilytics-package}
 \alias{civilytics}
 \alias{civilytics-package}
-\title{civilytics: Utilities Functions for Civilytics}
+\title{civilytics: Brand Themes, Color Palettes, and Utility Functions for Civilytics}
 \description{
-House R functions for Civilytics Consulting LLC. This package implements a variety of useful functions for creating and branding analyses produced by Civilytics Consulting LLC.
+Provides a complete ggplot2 brand theme system for Civilytics Consulting,
+including editorial light, dark, and slide-optimized themes; 10 curated
+color palettes; logo composition; and data-wrangling helpers for
+public-sector analysis.
 }
+\section{Themes}{
+
+\itemize{
+  \item [theme_civilytics()] -- editorial theme with warm paper background
+  \item [theme_civilytics_dark()] -- navy background variant
+  \item [theme_civilytics_slide()] -- transparent background, larger text
+}
+}
+
+\section{Color palettes}{
+
+\itemize{
+  \item [civilytics_colors] -- 53 named brand colors
+  \item [civilytics_palettes] -- 10 visualization palettes
+  \item [civilytics_palette()] -- extract colors by palette name
+  \item [scale_color_civilytics()] / [scale_fill_civilytics()] -- ggplot2 scales
+}
+}
+
 \seealso{
 Useful links:
 \itemize{

man/civilytics_colors.Rd

@@ -12,10 +12,12 @@ civilytics_colors
 }
 \description{
 A named character vector of all Civilytics brand colors, matching the CSS
-custom properties defined on www.civilytics.com (`--cv-*` variables).
+custom properties in the Civilytics design system (`--cv-*` variables).
+Includes full ramps for navy, ember, and violet, plus supporting hues
+(teal, plum, moss, brass) and semantic status colors.
 }
 \examples{
-civilytics_colors["accent"]
-civilytics_colors[c("ink", "paper")]
+civilytics_colors["ink"]
+civilytics_colors[c("navy_600", "ember_600", "teal_600")]
 }
 \keyword{datasets}

man/civilytics_pal.Rd

@@ -2,28 +2,23 @@
 % Please edit documentation in R/colors.R
 \name{civilytics_pal}
 \alias{civilytics_pal}
-\title{Civilytics brand color palette}
+\title{Civilytics palette function (closure)}
 \usage{
-civilytics_pal(name = "main", n = NULL)
+civilytics_pal(name = "qual", reverse = FALSE)
 }
 \arguments{
-\item{name}{Character. Palette name: `"main"`, `"sequential"`, or
-`"diverging"`. Defaults to `"main"`.}
+\item{name}{Character. Palette name. See `names(civilytics_palettes)`.}
 
-\item{n}{Integer or `NULL`. Number of colors to return. If `NULL`, returns
-all colors in the palette. If `n` exceeds the number of defined stops,
-colors are interpolated via [grDevices::colorRampPalette()].}
+\item{reverse}{Logical. Reverse the palette order. Default `FALSE`.}
 }
 \value{
-A character vector of hex color codes.
+A function that takes integer `n` and returns `n` hex color codes.
 }
 \description{
-Returns a character vector of hex codes from a named Civilytics palette.
-Available palettes: `"main"` (qualitative, up to 6), `"sequential"` (light
-to dark navy), `"diverging"` (orange–neutral–navy).
+Returns a closure `function(n)` suitable for passing to
+[ggplot2::discrete_scale()] or similar scale constructors.
 }
 \examples{
-civilytics_pal()            # all 6 qualitative colors
-civilytics_pal("sequential", n = 3)
-civilytics_pal("diverging",  n = 5)
+pal_fn <- civilytics_pal("qual")
+pal_fn(4)
 }

man/civilytics_palette.Rd

@@ -0,0 +1,30 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/colors.R
+\name{civilytics_palette}
+\alias{civilytics_palette}
+\title{Get colors from a Civilytics palette}
+\usage{
+civilytics_palette(name = "qual", n = NULL, reverse = FALSE)
+}
+\arguments{
+\item{name}{Character. Palette name. See `names(civilytics_palettes)`.}
+
+\item{n}{Integer or `NULL`. Number of colors to return. If `NULL`, returns
+all defined stops.}
+
+\item{reverse}{Logical. Reverse the palette order. Default `FALSE`.}
+}
+\value{
+A character vector of hex color codes.
+}
+\description{
+Returns a character vector of hex codes from a named Civilytics palette.
+For qualitative palettes, colors beyond the palette length recycle with a
+warning. For sequential and diverging palettes, colors are interpolated
+via [grDevices::colorRampPalette()].
+}
+\examples{
+civilytics_palette()                        # all 7 qualitative colors
+civilytics_palette("seq_navy", n = 5)       # 5-stop navy ramp
+civilytics_palette("div_navy_ember", n = 11, reverse = TRUE)
+}

man/civilytics_palettes.Rd

@@ -0,0 +1,50 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/colors.R
+\docType{data}
+\name{civilytics_palettes}
+\alias{civilytics_palettes}
+\title{Civilytics visualization palettes}
+\format{
+A named list of character vectors of hex color codes.
+}
+\usage{
+civilytics_palettes
+}
+\description{
+Named list of curated color palettes for data visualization. Qualitative
+palettes use distinct hues for categorical data; sequential palettes ramp
+through a single hue for ordered data; diverging palettes fan out from a
+neutral midpoint.
+}
+\section{Qualitative (categorical data)}{
+
+\describe{
+  \item{`qual`}{7 distinct hues: navy, ember, plum, violet, red, teal, ink-3}
+  \item{`qual_warm`}{Warm-leaning: ember, red, magenta, plum, violet}
+  \item{`qual_cool`}{Cool-leaning: navy, violet, plum, teal}
+}
+}
+
+\section{Sequential (ordered/continuous data)}{
+
+\describe{
+  \item{`seq_ember`}{Light to dark ember (9 stops)}
+  \item{`seq_navy`}{Light to dark navy (9 stops)}
+  \item{`seq_violet`}{Light to dark violet (9 stops)}
+  \item{`seq_paper_ink`}{Paper through ember/plum to ink (8 stops, good for heatmaps)}
+}
+}
+
+\section{Diverging (data with a meaningful midpoint)}{
+
+\describe{
+  \item{`div_navy_ember`}{Navy <-> paper <-> ember (9 stops)}
+  \item{`div_violet_ember`}{Violet <-> paper <-> ember (9 stops)}
+}
+}
+
+\examples{
+names(civilytics_palettes)
+civilytics_palettes[["qual"]]
+}
+\keyword{datasets}

man/scale_color_civilytics.Rd

@@ -4,25 +4,23 @@
 \alias{scale_color_civilytics}
 \title{Civilytics color scale for ggplot2}
 \usage{
-scale_color_civilytics(palette = "main", discrete = TRUE, ...)
+scale_color_civilytics(palette = "qual", discrete = TRUE, reverse = FALSE, ...)
 }
 \arguments{
-\item{palette}{Character. Palette name passed to [civilytics_pal()].
-Defaults to `"main"`.}
+\item{palette}{Character. Palette name. Defaults to `"qual"`.}
 
-\item{discrete}{Logical. `TRUE` (default) for a discrete scale; `FALSE` for
-a continuous gradient via [ggplot2::scale_color_gradientn()].}
+\item{discrete}{Logical. `TRUE` (default) for categorical data; `FALSE`
+for a continuous gradient via [ggplot2::scale_color_gradientn()].}
 
-\item{...}{Additional arguments passed to the underlying ggplot2 scale
-function.}
+\item{reverse}{Logical. Reverse the palette order. Default `FALSE`.}
+
+\item{...}{Additional arguments passed to the ggplot2 scale function.}
 }
 \value{
 A ggplot2 scale object.
 }
 \description{
-Applies a Civilytics brand palette to the `colour` aesthetic. Use
-`discrete = TRUE` for categorical variables and `discrete = FALSE` for
-continuous gradients.
+Applies a Civilytics brand palette to the `colour` aesthetic.
 }
 \examples{
 library(ggplot2)
@@ -32,5 +30,5 @@ ggplot(mpg, aes(displ, hwy, colour = class)) +
 
 ggplot(mpg, aes(displ, hwy, colour = cty)) +
   geom_point() +
-  scale_color_civilytics("sequential", discrete = FALSE)
+  scale_color_civilytics("seq_navy", discrete = FALSE)
 }

man/scale_fill_civilytics.Rd

@@ -4,25 +4,23 @@
 \alias{scale_fill_civilytics}
 \title{Civilytics fill scale for ggplot2}
 \usage{
-scale_fill_civilytics(palette = "main", discrete = TRUE, ...)
+scale_fill_civilytics(palette = "qual", discrete = TRUE, reverse = FALSE, ...)
 }
 \arguments{
-\item{palette}{Character. Palette name passed to [civilytics_pal()].
-Defaults to `"main"`.}
+\item{palette}{Character. Palette name. Defaults to `"qual"`.}
 
-\item{discrete}{Logical. `TRUE` (default) for a discrete scale; `FALSE` for
-a continuous gradient via [ggplot2::scale_fill_gradientn()].}
+\item{discrete}{Logical. `TRUE` (default) for categorical data; `FALSE`
+for a continuous gradient via [ggplot2::scale_fill_gradientn()].}
 
-\item{...}{Additional arguments passed to the underlying ggplot2 scale
-function.}
+\item{reverse}{Logical. Reverse the palette order. Default `FALSE`.}
+
+\item{...}{Additional arguments passed to the ggplot2 scale function.}
 }
 \value{
 A ggplot2 scale object.
 }
 \description{
-Applies a Civilytics brand palette to the `fill` aesthetic. Use
-`discrete = TRUE` for categorical variables and `discrete = FALSE` for
-continuous gradients.
+Applies a Civilytics brand palette to the `fill` aesthetic.
 }
 \examples{
 library(ggplot2)
@@ -32,5 +30,5 @@ ggplot(mpg, aes(class, fill = class)) +
 
 ggplot(faithfuld, aes(waiting, eruptions, fill = density)) +
   geom_tile() +
-  scale_fill_civilytics("sequential", discrete = FALSE)
+  scale_fill_civilytics("seq_ember", discrete = FALSE)
 }

man/theme_civilytics.Rd

@@ -14,8 +14,10 @@ theme_civilytics(
   rel_large = 16/14,
   ink = unname(civilytics_colors["ink"]),
   paper = unname(civilytics_colors["paper"]),
-  accent = unname(civilytics_colors["accent"]),
-  strip_color = unname(civilytics_colors["paper_2"])
+  accent = unname(civilytics_colors["ember_600"]),
+  strip_color = unname(civilytics_colors["paper_2"]),
+  grid = c("y", "x", "both", "none"),
+  paper_bg = TRUE
 )
 }
 \arguments{
@@ -45,10 +47,18 @@ Default `11/14`.}
 [civilytics_colors]`["paper"]` (`#FAF7F2`).}
 
 \item{accent}{Character. Hex code for accent/highlight color. Defaults to
-[civilytics_colors]`["accent"]` (`#C25311`).}
+[civilytics_colors]`["ember_600"]` (`#C25311`).}
 
 \item{strip_color}{Character. Hex code for facet strip background. Defaults
 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).}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
@@ -59,6 +69,11 @@ Civilytics brand color palette and typography. Requires ggplot2 >= 4.0.0
 for the `ink`, `paper`, and `accent` base-theme parameters.
 }
 \details{
+Produces an editorial, Pew-style layout: visible x-axis line to ground
+the data, light horizontal gridlines for reference, no panel border or
+y-axis line. Plot title and caption are left-aligned to the full plot
+region.
+
 Brand fonts (Inter for UI text, Libre Franklin for titles) are loaded
 automatically via [showtext] when the package is attached. Call
 [civilytics_load_fonts()] to reload them if needed.
@@ -66,13 +81,21 @@ automatically via [showtext] when the package is attached. Call
 \examples{
 \dontrun{
 library(ggplot2)
+
+# Default editorial theme
 ggplot(mpg, aes(displ, hwy)) +
   geom_point() +
   theme_civilytics()
 
+# With both gridlines and brand colors
 ggplot(mpg, aes(displ, hwy, colour = class)) +
   geom_point() +
   scale_color_civilytics() +
-  theme_civilytics()
+  theme_civilytics(grid = "both")
+
+# Transparent background for embedding
+ggplot(mpg, aes(displ, hwy)) +
+  geom_point() +
+  theme_civilytics(paper_bg = FALSE)
 }
 }

man/theme_civilytics_dark.Rd

@@ -13,9 +13,11 @@ theme_civilytics_dark(
   rel_tiny = 11/14,
   rel_large = 16/14,
   ink = unname(civilytics_colors["paper"]),
-  paper = unname(civilytics_colors["navy_dark"]),
-  accent = unname(civilytics_colors["accent_dark"]),
-  strip_color = unname(civilytics_colors["navy"])
+  paper = unname(civilytics_colors["navy_700"]),
+  accent = unname(civilytics_colors["ember_400"]),
+  strip_color = unname(civilytics_colors["navy_600"]),
+  grid = c("y", "x", "both", "none"),
+  paper_bg = TRUE
 )
 }
 \arguments{
@@ -45,31 +47,33 @@ Default `11/14`.}
 [civilytics_colors]`["paper"]` (`#FAF7F2`).}
 
 \item{accent}{Character. Hex code for accent/highlight color. Defaults to
-[civilytics_colors]`["accent"]` (`#C25311`).}
+[civilytics_colors]`["ember_600"]` (`#C25311`).}
 
 \item{strip_color}{Character. Hex code for facet strip background. Defaults
 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).}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
 }
 \description{
-A convenience wrapper around [theme_civilytics()] with dark-background
-defaults: navy (`#1A2E4A`) background, warm off-white (`#FAF7F2`) text, and
-a lighter orange accent (`#E07840`) suitable for dark backgrounds. Pair with
-`make_logo_grob(variant = "dark")` to use the white logo.
+Convenience wrapper around [theme_civilytics()] with dark-background
+defaults: navy (`#1A2E4A`) paper, warm off-white (`#FAF7F2`) ink, and
+a lighter ember accent (`#E07840`). Facet strips use primary navy.
 }
 \details{
-All parameters from [theme_civilytics()] are accepted and override the dark
-defaults.
+Pair with `make_logo_grob(variant = "dark")` for the white logo.
 }
 \examples{
 \dontrun{
 library(ggplot2)
-ggplot(mpg, aes(displ, hwy)) +
-  geom_point() +
-  theme_civilytics_dark()
-
 ggplot(mpg, aes(displ, hwy, colour = class)) +
   geom_point() +
   scale_color_civilytics() +

man/theme_civilytics_slide.Rd

@@ -0,0 +1,79 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/theme.R
+\name{theme_civilytics_slide}
+\alias{theme_civilytics_slide}
+\title{Slide-friendly Civilytics ggplot2 theme}
+\usage{
+theme_civilytics_slide(
+  font_size = 18,
+  font_family = CV_FONT_SANS,
+  title_family = CV_FONT_DISPLAY,
+  line_size = 0.5,
+  rel_small = 12/14,
+  rel_tiny = 11/14,
+  rel_large = 16/14,
+  ink = unname(civilytics_colors["ink"]),
+  paper = unname(civilytics_colors["paper"]),
+  accent = unname(civilytics_colors["ember_600"]),
+  strip_color = unname(civilytics_colors["paper_2"]),
+  grid = c("y", "x", "both", "none"),
+  paper_bg = FALSE
+)
+}
+\arguments{
+\item{font_size}{Numeric. Base font size in points. Default `14`.}
+
+\item{font_family}{Character. Font family for body/axis text. Default
+`"Inter"` (loaded via showtext).}
+
+\item{title_family}{Character. Font family for plot titles and strip labels.
+Default `"Libre Franklin"` (loaded via showtext).}
+
+\item{line_size}{Numeric. Base line width. Default `0.5`.}
+
+\item{rel_small}{Numeric. Scale factor for small text relative to
+`font_size`. Default `12/14`.}
+
+\item{rel_tiny}{Numeric. Scale factor for tiny text relative to `font_size`.
+Default `11/14`.}
+
+\item{rel_large}{Numeric. Scale factor for large text (titles) relative to
+`font_size`. Default `16/14`.}
+
+\item{ink}{Character. Hex code for foreground/text color. Defaults to
+[civilytics_colors]`["ink"]` (`#0E1A2B`).}
+
+\item{paper}{Character. Hex code for background color. Defaults to
+[civilytics_colors]`["paper"]` (`#FAF7F2`).}
+
+\item{accent}{Character. Hex code for accent/highlight color. Defaults to
+[civilytics_colors]`["ember_600"]` (`#C25311`).}
+
+\item{strip_color}{Character. Hex code for facet strip background. Defaults
+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).}
+}
+\value{
+A complete ggplot2 [ggplot2::theme()] object.
+}
+\description{
+Variant of [theme_civilytics()] sized for Reveal.js slides or PowerPoint
+exports: larger base font (18pt), transparent background, wider margins,
+and a heavier x-axis line. Gridlines default to horizontal only.
+}
+\examples{
+\dontrun{
+library(ggplot2)
+ggplot(mpg, aes(displ, hwy, colour = class)) +
+  geom_point() +
+  scale_color_civilytics() +
+  theme_civilytics_slide()
+}
+}