Design token system for Mob apps.

A theme is a compiled %Mob.Theme{} struct — a flat map of semantic tokens for colors, spacing, radii, and scale factors. The renderer resolves these tokens at render time so every component picks up the active theme automatically.

Using a named theme

Named themes are plain modules that export theme/0. Pass the module to use Mob.App:

use Mob.App, theme: MobThemes.Obsidian   # (the mob_themes style package)

Override individual tokens without leaving the theme:

use Mob.App, theme: {MobThemes.Obsidian, primary: :rose_500}

Anyone can publish a theme as a Hex package — any module with theme/0 returning a Mob.Theme.t() works:

use Mob.App, theme: AcmeCorp.BrandTheme

Building a theme from scratch

Pass a keyword list of overrides against the neutral base:

use Mob.App, theme: [primary: :emerald_500, type_scale: 1.1]

Or change the theme at runtime (e.g. for accessibility or user preference):

Mob.Theme.set(MobThemes.Obsidian)
Mob.Theme.set({MobThemes.Obsidian, type_scale: 1.2})
Mob.Theme.set({MobThemes.Obsidian, text_scale: 1.3})   # the user's text size
Mob.Theme.set(primary: :pink_500)

Base theme

When no theme is set the renderer uses the neutral base — plain dark grays with a standard blue primary. Functional, not opinionated. Good enough for hello world; swap in a named theme when you want personality.

Token reference

Semantic color tokens

:primary        — main action colour          (default :blue_500)
:on_primary     — text/icons on primary        (default :white)
:secondary      — secondary action colour      (default :gray_600)
:on_secondary   — text/icons on secondary      (default :white)
:background     — page/screen background       (default :gray_900)
:on_background  — text on background           (default :gray_100)
:surface        — card / sheet background      (default :gray_800)
:surface_raised — elevated card background     (default :gray_700)
:on_surface     — text/icons on surface        (default :gray_100)
:muted          — secondary/placeholder text   (default :gray_500)
:error          — error state colour           (default :red_500)
:on_error       — text/icons on error          (default :white)
:border         — dividers and outlines        (default :gray_700)

Spacing tokens (scaled by space_scale)

:space_xs  →  4 × scale
:space_sm  →  8 × scale
:space_md  → 16 × scale
:space_lg  → 24 × scale
:space_xl  → 32 × scale

Radius tokens

:radius_sm   → theme.radius_sm   (default  6)
:radius_md   → theme.radius_md   (default 10)
:radius_lg   → theme.radius_lg   (default 16)
:radius_pill → theme.radius_pill (default 100)

Scale factors

type_scale:  1.0  # multiply the text size tokens (:sm, :base, :xl…) by this
text_scale:  1.0  # multiply every text_size / font_size prop, number or token
space_scale: 1.0  # multiply all spacing tokens by this

type_scale belongs to the theme's design: it scales the token sizes and leaves a numeric text_size (a size pinned to a design) alone. text_scale is the user's text-size preference (a Settings choice such as Small … Largest): the renderer multiplies it into every node's text_size and font_size prop, numeric or token, so an app written in exact numbers still grows. Only sizes on the node scale: a :text with no text_size keeps the platform default (give it :base to follow), and a sized :icon's glyph grows with it. Not scaled: a Canvas text op's size (it's in the drawing's coordinates) and sizes nested in a plugin's own props (a style map). It multiplies the OS font scale where native follows one: Android text sizes are sp; on iOS, custom-font text (Font.custom(_:size:)) follows Dynamic Type, while system-font text and the UIKit-backed text field are fixed points. At 1.0 (the default) every value reaches native exactly as written. Set it with the rest of the theme, and keep it when you switch themes:

Mob.Theme.set({MyApp.Theme.Dark, text_scale: 1.3})

Font tokens

fonts is a name → value map, resolved by the renderer exactly like colors (font: :heading walks this map, same two-step shape as text_color: :primary). :default is special — set it and the renderer injects it automatically onto any node that doesn't specify its own font:, so the whole app picks up a custom font without repeating it everywhere:

Mob.Theme.set(
  fonts: %{
    default: Mob.Theme.font("Inter-Regular", from_file: "priv/fonts/Inter-Regular.ttf"),
    heading: Mob.Theme.font("Inter-Bold", from_file: "priv/fonts/Inter-Bold.ttf")
  }
)

# in render/1:
%{type: :text, props: %{text: "Section", font: :heading}, children: []}
%{type: :text, props: %{text: "Body copy"}, children: []}  # gets :default automatically

font_fallback is an ordered list of font names tried, in order, if the resolved font can't be loaded on-device. Empty by default (the platform's own system-font fallback still applies) — set it when you want an explicit intermediate fallback before that.

A font value is either built with Mob.Theme.font/2 (recommended — it computes the Android name from the actual bundled file) or a bare string used as-is on both platforms.