diff --git a/README.Rmd b/README.Rmd
index e0175b1..33eb0c3 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -187,15 +187,63 @@ ggplot(mpg, aes(displ, hwy)) +
 
 Add the Civilytics logo to any ggplot using the pipe-friendly
 `civilytics_logo()` or the lower-level `add_logo()` / `make_logo_grob()`.
+The logo is automatically right-aligned below the plot area. Wrap the
+ggplot chain in parentheses before piping --- R's `|>` binds tighter
+than `+`.
 
-```r
-library(civilytics)
-library(ggplot2)
+### Wordmark on a light plot
 
-(ggplot(mpg, aes(displ, hwy)) +
-  geom_point() +
-  theme_civilytics()) |>
-  civilytics_logo()
+```{r logo-wordmark, fig.height = 4.5, fig.width = 7}
+p <- ggplot(mpg, aes(displ, hwy, colour = class)) +
+  geom_point(size = 2) +
+  scale_color_civilytics() +
+  labs(
+    title   = "Fuel economy by engine displacement",
+    caption = "Source: EPA fuel economy data (ggplot2::mpg)",
+    x = "Displacement (L)", y = "Highway MPG"
+  ) +
+  theme_civilytics()
+
+grid::grid.draw(civilytics_logo(p))
+```
+
+### Mark on a dark plot
+
+Use `type = "mark"` for the compact icon and `variant = "dark"` to
+match a dark background.
+
+```{r logo-dark, fig.height = 4.5, fig.width = 7}
+p_dark <- ggplot(mpg, aes(displ, hwy, colour = factor(cyl))) +
+  geom_point(size = 2) +
+  scale_color_civilytics() +
+  labs(
+    title  = "Engine size vs. highway fuel economy",
+    colour = "Cylinders",
+    x = "Displacement (L)", y = "Highway MPG"
+  ) +
+  theme_civilytics_dark()
+
+grid::grid.draw(civilytics_logo(p_dark, type = "mark", variant = "dark"))
+```
+
+### Multi-plot layout with logo
+
+Use `add_logo_ga()` to attach a single logo below a row of plots.
+
+```{r logo-multi, fig.height = 4.5, fig.width = 9}
+p1 <- ggplot(mpg, aes(class, fill = class)) +
+  geom_bar(show.legend = FALSE) +
+  scale_fill_civilytics() +
+  labs(title = "Vehicle counts", x = NULL, y = NULL) +
+  theme_civilytics(grid = "y")
+
+p2 <- ggplot(mpg, aes(displ, hwy)) +
+  geom_point(colour = civilytics_colors["navy_600"], size = 1.5) +
+  labs(title = "Displacement vs. MPG", x = "Displacement (L)", y = "Highway MPG") +
+  theme_civilytics(grid = "y")
+
+logo <- make_logo_grob()
+grid::grid.draw(add_logo_ga(list(p1, p2), logo))
 ```
 
 ## Other utilities
diff --git a/README.md b/README.md
index 9dec9e9..cf9422a 100644
--- a/README.md
+++ b/README.md
@@ -154,18 +154,71 @@ ggplot(mpg, aes(displ, hwy)) +
 
 Add the Civilytics logo to any ggplot using the pipe-friendly
 `civilytics_logo()` or the lower-level `add_logo()` /
-`make_logo_grob()`.
+`make_logo_grob()`. The logo is automatically right-aligned below the
+plot area. Wrap the ggplot chain in parentheses before piping — R’s `|>`
+binds tighter than `+`.
+
+### Wordmark on a light plot
 
 ``` r
-library(civilytics)
-library(ggplot2)
+p <- ggplot(mpg, aes(displ, hwy, colour = class)) +
+  geom_point(size = 2) +
+  scale_color_civilytics() +
+  labs(
+    title   = "Fuel economy by engine displacement",
+    caption = "Source: EPA fuel economy data (ggplot2::mpg)",
+    x = "Displacement (L)", y = "Highway MPG"
+  ) +
+  theme_civilytics()
 
-(ggplot(mpg, aes(displ, hwy)) +
-  geom_point() +
-  theme_civilytics()) |>
-  civilytics_logo()
+grid::grid.draw(civilytics_logo(p))
 ```
 
+<img src="man/figures/README-logo-wordmark-1.png" alt="" width="100%" />
+
+### Mark on a dark plot
+
+Use `type = "mark"` for the compact icon and `variant = "dark"` to match
+a dark background.
+
+``` r
+p_dark <- ggplot(mpg, aes(displ, hwy, colour = factor(cyl))) +
+  geom_point(size = 2) +
+  scale_color_civilytics() +
+  labs(
+    title  = "Engine size vs. highway fuel economy",
+    colour = "Cylinders",
+    x = "Displacement (L)", y = "Highway MPG"
+  ) +
+  theme_civilytics_dark()
+
+grid::grid.draw(civilytics_logo(p_dark, type = "mark", variant = "dark"))
+```
+
+<img src="man/figures/README-logo-dark-1.png" alt="" width="100%" />
+
+### Multi-plot layout with logo
+
+Use `add_logo_ga()` to attach a single logo below a row of plots.
+
+``` r
+p1 <- ggplot(mpg, aes(class, fill = class)) +
+  geom_bar(show.legend = FALSE) +
+  scale_fill_civilytics() +
+  labs(title = "Vehicle counts", x = NULL, y = NULL) +
+  theme_civilytics(grid = "y")
+
+p2 <- ggplot(mpg, aes(displ, hwy)) +
+  geom_point(colour = civilytics_colors["navy_600"], size = 1.5) +
+  labs(title = "Displacement vs. MPG", x = "Displacement (L)", y = "Highway MPG") +
+  theme_civilytics(grid = "y")
+
+logo <- make_logo_grob()
+grid::grid.draw(add_logo_ga(list(p1, p2), logo))
+```
+
+<img src="man/figures/README-logo-multi-1.png" alt="" width="100%" />
+
 ## Other utilities
 
 The package also includes helpers for public-sector data analysis:
diff --git a/man/figures/README-logo-dark-1.png b/man/figures/README-logo-dark-1.png
new file mode 100644
index 0000000..02a8f5d
Binary files /dev/null and b/man/figures/README-logo-dark-1.png differ
diff --git a/man/figures/README-logo-multi-1.png b/man/figures/README-logo-multi-1.png
new file mode 100644
index 0000000..60fe191
Binary files /dev/null and b/man/figures/README-logo-multi-1.png differ
diff --git a/man/figures/README-logo-wordmark-1.png b/man/figures/README-logo-wordmark-1.png
new file mode 100644
index 0000000..f70a849
Binary files /dev/null and b/man/figures/README-logo-wordmark-1.png differ