Theme tokens

Status: Implemented (API 1.21). Read-only access to the player’s Appearance: the style, the theme, its colours, lengths and text metrics, and the icon set.

Function table: ui. Related: The UI Kit.

Kit widgets switch style and theme by themselves. Use the tokens only for your own drawing, so it matches the widgets around it.

Functions

C	Lua	Gives
`cl_ui_fancy()`	`cl.ui.fancy()`	`true` while your mod’s screens draw in the Fancy style
`cl_ui_hud_fancy()`	`cl.ui.hud_fancy()`	`true` while the HUD draws in the Fancy style
`cl_ui_theme(buf, cap, &len)`	`cl.ui.theme()`	The theme: a preset id (`"night"`, `"aurora"`, `"ember"`, …)
`cl_ui_color(name)`	`cl.ui.color(name)`	A colour token as `0xAARRGGBB` (0 for an unknown name)
`cl_ui_length(name)`	`cl.ui.length(name)`	A length token in design pixels (4 design pixels = 1 GUI pixel)
`cl_ui_text_width(s, style)`	`cl.ui.text_width(s, style)`	The width of text in a kit style, in GUI pixels, in the font the current style uses
`cl_ui_line_height(style)`	`cl.ui.line_height(style)`	The line height of a kit style in GUI pixels
`cl_ui_generation()`	`cl.ui.generation()`	A number that changes whenever the style, the theme or a token changes
`cl_ui_has_icon(name)`	`cl.ui.has_icon(name)`	`true` when the icon set has the icon

Text styles: CL_UI_TEXT_BODY, SMALL, H1, H2, H3, BUTTON, CHIP (Lua: "body", "small", …). In the Vanilla style every style is the game font, 9 pixels high.

Colour names

Name	What it is
`panel`, `raised`, `sunken`, `selected`	Surfaces: containers, raised rows, recessed wells, the selected item
`control`, `control_hover`, `control_press`, `control_off`	Button plates by state
`on_surface`, `on_surface_2`, `on_surface_3`	Text: primary (white), secondary, tertiary
`hairline`	The thin edge of panels
`hud_panel`	The HUD panel material
`accent`, `accent_ink`	The theme’s accent and the glyph colour on controls (white in the default theme)
`overlay`, `overlay_front`, `overlay_dense`, `overlay_in_game`	The theme’s background overlay at its strengths
`danger`, `warn`, `ok`	States
`focus`	The keyboard focus ring

Length names

radius.ctl (controls), radius.box (panels), radius.inner, stroke.hairline, space.1 … space.16, button_h, field_h, toggle, row_min_h, sidebar_w, header_h, footer_h, and the others of the design system. Divide by 4 for GUI pixels:

local radius = cl.ui.length("radius.box") / 4      -- GUI pixels
local fill = cl.ui.color("panel")

Caching your drawing

Read tokens when you build something, not every frame, and keep the values until cl.ui.generation() changes:

local cached_gen, panel_colour = -1, 0
local function colours()
  local gen = cl.ui.generation()
  if gen ~= cached_gen then
    cached_gen = gen
    panel_colour = cl.ui.color("hud_panel")
  end
  return panel_colour
end

Icons

The icon set is Material Symbols Rounded (filled), drawn sharp at any size: back, check, chevron-down, chevron-left, chevron-right, chevron-up, clock, close, copy, download, drag, edit, external, eye, eye-off, filter, folder, friends, grid, heart, hud, image, info, keyboard, label, language, layers, link, lock, marker, minus, mods, moon, more, mouse, move, network, news, performance, pin, play, plus, power, redo, refresh, reset, scale, search, send, settings, shield, sliders, sort, sound, star, stats, store, sun, sword, trash, trophy, undo, upload, user-plus, video, warning, website, world and more (cl.ui.has_icon tells). Anywhere an icon name is taken, "<mod id>:<path>" draws your own GUI sprite instead.