Log inGet started
Package

zui.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

theme

Theme tokens for zui (Layer 2). Reads through ui.getToken(name) first so a loaded engine theme propagates automatically; falls back to in-module defaults that cover every named color used by the demos. Also owns the Luau-side $variable cascade — register / load resolve references end-to-end (cycle-detected) and push flat values to ui.registerTheme.

Exports

  • M.with(overrides: TokenMap?) -> ThemeView — read-only view with overlays on top of engine/defaults.
  • M.defaults() -> TokenMap — raw default token map (same reference each call).
  • M.tokenNames() -> { string } — sorted list of shipped token names.
  • M.resolve(theme: any) -> (ResolvedTheme?, string?) — flatten a theme table ($var → literal). Returns (nil, errMsg) on failure.
  • M.resolveTokens(theme) -> (TokenMap?, string?) — re-export from cascade.
  • M.resolveStyles(theme, tokens) -> (StyleMap?, string?) — re-export from cascade.
  • M.register(name: string, theme: any) -> (boolean, string?) — resolve and push to ui.registerTheme.
  • M.load(name: string) -> (boolean, string?) — require @builtin::themes.<name> and register it.
  • M.activate(name: string) -> boolean — thin wrapper over ui.setTheme(name).
  • M.default: ThemeView — module-level token view with no overrides.

Types:

  • TokenMap = { [string]: any }
  • StyleMap = { [string]: { [string]: any } }
  • Theme = { name: string?, tokens: TokenMap?, styles: StyleMap? }
  • ResolvedTheme = { name: string, tokens: TokenMap, styles: StyleMap }
  • ThemeView — read-only metatable proxy; writes throw.

Usage

local Theme = require("@builtin::modules.zui.theme")

Theme.load("dark")          -- require + register the built-in dark theme
Theme.activate("dark")      -- ui.setTheme("dark")

local view = Theme.with({ accent = "#ff0" })
print(view.accent)          -- "#ff0"
print(view.bg)              -- engine token or default

Notes

  • register overrides theme.name with the caller-supplied name so listThemes() / setTheme(name) find it under the requested key (mirrors the pre-Phase-4 #942 fix).
  • The cascade is cycle-detected — broken inputs surface as structured (false, errMsg) returns instead of silently producing garbage colors.
  • M.default is built at module-load time, after M is fully populated, so its function-fallback __index resolves correctly.
  • ThemeView writes raise — use Z.themeWith({...}) to get an overlay view rather than mutating the existing one.