% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/theme.R
\name{theme_civilytics}
\alias{theme_civilytics}
\title{Civilytics ggplot2 theme}
\usage{
theme_civilytics(
  font_size = 16,
  font_family = CV_FONT_SANS,
  title_family = CV_FONT_DISPLAY,
  line_size = 0.5,
  rel_small = 12/14,
  rel_tiny = 11/14,
  rel_large = 20/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 = TRUE
)
}
\arguments{
\item{font_size}{Numeric. Base font size in points. Default `16`.}

\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 `20/14` (~1.43x), matching the Civilytics editorial
design system.}

\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{
A complete ggplot2 theme built on [ggplot2::theme_grey()] using the
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.
}
\section{Font size hierarchy}{

All text sizes are derived from `font_size` using relative scale factors.
At the default `font_size = 14`:

| Element | Scale factor | Default size |
|:--------|:-------------|:-------------|
| Plot title | `rel_large` (1.43x) | ~23 pt |
| Subtitle | 1.0x | 16 pt |
| Axis text (tick labels) | `rel_small` (0.86x) | ~14 pt |
| Axis titles | `rel_small` (0.86x) | ~14 pt |
| Legend text | `rel_small` (0.86x) | ~14 pt |
| Caption | `rel_tiny` (0.79x) | ~13 pt |
| Legend title | `rel_tiny` (0.79x) | ~13 pt |
| Strip text (facets) | `rel_small` (0.86x) | ~14 pt |

To uniformly scale all text, change `font_size`. To adjust only the title
prominence, change `rel_large`. When using [civilytics_logo()] to add a
logo below the plot, pass `font_scale` to compensate for viewport
shrinkage.
}

\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(grid = "both")

# Transparent background for embedding
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  theme_civilytics(paper_bg = FALSE)

# Larger text for poster or display
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  theme_civilytics(font_size = 18)
}
}