TermUI.Theme (TermUI v0.2.0)

Theme system for application-wide visual consistency.

Themes define colors, semantic meanings, and component style defaults. The theme system supports runtime switching and notifies subscribers of changes.

Theme Structure

A theme contains:

:name - Theme identifier (e.g., :dark, :light)
:colors - Base colors (background, foreground, primary, etc.)
:semantic - Semantic colors (success, warning, error, etc.)
:components - Per-component style defaults

Built-in Themes

:dark - Dark background with light text (default)
:light - Light background with dark text
:high_contrast - High contrast for accessibility

Examples

# Start theme server
Theme.start_link(theme: :dark)

# Get current theme
theme = Theme.get_theme()

# Switch themes at runtime
Theme.set_theme(:light)

# Subscribe to theme changes
Theme.subscribe()
receive do
  {:theme_changed, new_theme} -> handle_change(new_theme)
end

# Get colors
bg = Theme.get_color(:background)
error = Theme.get_semantic(:error)

# Get component style
style = Theme.get_component_style(:button, :focused)

Summary

Types

color()

colors()

component_styles()

semantic()

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

from(opts)

Creates a theme from a keyword list or map, merging with a base theme.

get_builtin(name)

Gets a built-in theme by name.

get_color(name, server \\ __MODULE__)

Gets a base color from the current theme.

get_component_style(component, variant, server \\ __MODULE__)

Gets a component style from the current theme.

get_semantic(name, server \\ __MODULE__)

Gets a semantic color from the current theme.

get_theme(server \\ __MODULE__)

Gets the current theme.

list_builtin()

Lists all available built-in themes.

set_theme(theme, server \\ __MODULE__)

Sets the current theme.

start_link(opts \\ [])

Starts the theme server.

style_from_theme(component, variant, overrides \\ [], server \\ __MODULE__)

Creates a style from theme values with optional overrides.

subscribe(server \\ __MODULE__)

Subscribes the calling process to theme change notifications.

unsubscribe(server \\ __MODULE__)

Unsubscribes the calling process from theme change notifications.

validate(theme)

Validates a theme struct.

Types

color()

@type color() :: TermUI.Style.color()

colors()

@type colors() :: %{
  background: color(),
  foreground: color(),
  primary: color(),
  secondary: color(),
  accent: color()
}

component_styles()

@type component_styles() :: %{
  required(atom()) => %{required(atom()) => TermUI.Style.t()}
}

semantic()

@type semantic() :: %{
  success: color(),
  warning: color(),
  error: color(),
  info: color(),
  muted: color()
}

t()

@type t() :: %TermUI.Theme{
  colors: colors(),
  components: component_styles(),
  name: atom(),
  semantic: semantic()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

from(opts)

@spec from(keyword() | map()) :: {:ok, t()} | {:error, term()}

Creates a theme from a keyword list or map, merging with a base theme.

Options

:base - Base theme to merge with (default :dark)
:name - Theme name
:colors - Color overrides
:semantic - Semantic color overrides
:components - Component style overrides

Examples

# Create custom theme based on dark
{:ok, theme} = Theme.from(
  base: :dark,
  name: :my_theme,
  colors: %{primary: :magenta}
)

get_builtin(name)

@spec get_builtin(atom()) :: {:ok, t()} | {:error, :not_found}

Gets a built-in theme by name.

get_color(name, server \\ MODULE)

@spec get_color(atom(), GenServer.server()) :: color() | nil

Gets a base color from the current theme.

Examples

Theme.get_color(:background)  # => :black
Theme.get_color(:primary)     # => :blue

get_component_style(component, variant, server \\ MODULE)

@spec get_component_style(atom(), atom(), GenServer.server()) ::
  TermUI.Style.t() | nil

Gets a component style from the current theme.

Examples

Theme.get_component_style(:button, :focused)
Theme.get_component_style(:text_input, :normal)

get_semantic(name, server \\ MODULE)

@spec get_semantic(atom(), GenServer.server()) :: color() | nil

Gets a semantic color from the current theme.

Examples

Theme.get_semantic(:error)    # => :red
Theme.get_semantic(:success)  # => :green

get_theme(server \\ MODULE)

@spec get_theme(GenServer.server()) :: t()

Gets the current theme.

list_builtin()

@spec list_builtin() :: [atom()]

Lists all available built-in themes.

set_theme(theme, server \\ MODULE)

@spec set_theme(atom() | t(), GenServer.server()) :: :ok | {:error, term()}

Sets the current theme.

Accepts a theme name atom (for built-in themes) or a Theme struct. Notifies all subscribers of the change.

Examples

Theme.set_theme(:light)
Theme.set_theme(%Theme{name: :custom, ...})

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the theme server.

Options

:theme - Initial theme (atom name or Theme struct, default :dark)
:name - GenServer name (default Elixir.TermUI.Theme)

Examples

Theme.start_link(theme: :dark)
Theme.start_link(theme: :light, name: MyApp.Theme)

style_from_theme(component, variant, overrides \\ [], server \\ MODULE)

@spec style_from_theme(atom(), atom(), keyword(), GenServer.server()) ::
  TermUI.Style.t()

Creates a style from theme values with optional overrides.

Useful for components that want to use theme defaults but allow customization.

Examples

# Use theme button style as base, override foreground
style = Theme.style_from_theme(:button, :normal, fg: :red)

unsubscribe(server \\ MODULE)

@spec unsubscribe(GenServer.server()) :: :ok

Unsubscribes the calling process from theme change notifications.

validate(theme)

@spec validate(t()) :: :ok | {:error, [String.t()]}

Validates a theme struct.

Returns :ok if valid, {:error, reasons} if invalid.