Theming

Rendro.Theme is a pure, inert design-token value: semantic color roles plus typography, resolved once and threaded through every recipe's three-rung pattern (document/2 → page_template/1 → sections/2). It performs no I/O and touches no registry — it never reaches the deterministic render pipeline directly.

For a complete preset choice and adoption route, see Presets. This guide stays focused on manual theme tokens and caller-owned brand inputs.

Rendro.Recipes.Invoice.document(data, theme: Rendro.Theme.from_brand(accent: "#0E7C76"))

Start with an accent

The narrowest branded theme is a single accent: seed. from_brand/2 coerces a hex string to an integer {r, g, b} tuple at the authoring boundary, keeps every other role at the unbranded default, and derives a readable on_accent for you.

# docs-contract: theming-accent-only
import ExUnit.Assertions

theme = Rendro.Theme.from_brand(accent: "#0E7C76")
resolved = Rendro.Theme.resolve(theme)

# accent seed coerced hex -> tuple
assert resolved.colors.accent == {14, 124, 118}
# on_accent derived to white: teal luminance ~0.16, greater contrast vs background
assert resolved.colors.on_accent == {255, 255, 255}

on_accent is a sensible readable default, picked by comparing WCAG contrast between the accent and the theme's own neutral poles (background vs ink) — it is not a WCAG-AA/AAA or PDF-UA conformance claim. Mid-tone accents can miss 4.5:1 either way. Pass an explicit on_accent: to override the derivation whenever your accent needs one.

The heuristic proven both ways

A light accent flips the derivation to the opposite pole. Amber (luminance ~0.50) has far more contrast against dark ink than against a white background, so on_accent resolves to ink instead of white:

# docs-contract: theming-accent-contrast-both-ways
import ExUnit.Assertions

amber = Rendro.Theme.resolve(Rendro.Theme.from_brand(accent: "#E6B450"))
# ink, because amber is light (luminance ~0.50) -- again a readable default,
# not a WCAG-AA/PDF-UA guarantee, and overridable via on_accent:
assert amber.colors.on_accent == {16, 24, 39}

The fuller form

Beyond accent:, from_brand/2 accepts any color role plus an explicit on_accent: override, and opts for mode:/density::

theme =
  Rendro.Theme.from_brand(
    accent: "#7A2E8F",
    ink: {20, 20, 24},
    surface: {245, 240, 250},
    on_accent: {255, 255, 255}
  )

Swap "#7A2E8F" for your color here — any hex string or {r, g, b} tuple works; from_brand/2 validates every resolved role via Rendro.Color.validate/1 and raises an instructive ArgumentError on an invalid token.

brand: and theme: are orthogonal

brand: answers who (a registered font + logo asset on data.brand); theme: answers how (color roles + typography). from_brand/2 emits tokens only — it never registers a font or an image, and reading a bare %Rendro.Theme{} does not add any registry-adjacent field to the value. Rendro.Recipes.BrandedInvoice.document/2 composes both without either leaking into the other:

# docs-contract: theming-brand-orthogonal
import ExUnit.Assertions

data = %{
  id: "INV-2026-201",
  date: ~D[2026-05-01],
  items: [%{name: "Consulting", qty: 4, price: 1500}],
  brand: %{font_name: :brand_heading, logo_name: :company_logo}
}

theme = Rendro.Theme.from_brand(accent: "#0E7C76")

# from_brand/2 alone returns a bare %Theme{} -- no registry side-effect
assert %Rendro.Theme{} = theme
refute Map.has_key?(Map.from_struct(theme), :font_registry)
refute Map.has_key?(Map.from_struct(theme), :asset_registry)

doc = Rendro.Recipes.BrandedInvoice.document(data, theme: theme)

# assets registered via data.brand
assert Map.has_key?(doc.font_registry.fonts, :brand_heading)
assert Map.has_key?(doc.asset_registry.assets, :company_logo)
# accent registered via theme: -- the same coerced tuple, orthogonal to assets
assert Rendro.Theme.resolve(theme).colors.accent == {14, 124, 118}

Light and dark, for free

Every recipe reads color roles, never literals, so Rendro.Theme.dark/1 gives every recipe a full-page dark background with zero recipe-level dark code. Dark is a screen-oriented convenience: it carries no print, accessibility, PDF-UA, or WCAG-contrast support claim — see priv/support_matrix.json's theming.dark boundaries.

Gallery

Eleven rendered rows prove the theming contract end to end: the unbranded default, dark mode, and a branded accent, each rendered through the pinned deterministic pdfium lane and hash-checked against assets/rendro/artifacts.json.

Every hash is generated and verified by mix rendro.launch_artifacts.gen / mix rendro.launch_artifacts.check against assets/rendro/artifacts.json — the same pinned pdfium lane the reader-quality sign-off evidence uses.