# `theme`

Colors follow the active theme, including the fade while it switches, so read them every frame
instead of caching them.

| Function | Returns |
|----------|---------|
| `theme.color(role)` | Current ARGB color of a role; errors on an unknown role |
| `theme.colors()` | Table of every role to its color |
| `theme.name()` | Id of the active theme, e.g. `"default"` |
| `theme.list()` | Ids of all installed themes, built-ins first |
| `theme.set(name)` | Activates a theme and saves the choice; `false` if there is no such id |
| `theme.set_color(role, color, name?)` | Recolors one role of a custom theme, the active one by default |
| `theme.set_colors(colors, name?)` | Recolors several roles at once from a `{ role = color }` table |

`set_color` and `set_colors` save the theme to disk and sync it like an edit in the theme editor, so
call them on a change, not every frame. Built-in themes can't be edited — they error, as do an
unknown role or theme id. Clone a built-in in the theme manager first and edit the copy.

## Roles

| Group | Roles |
|-------|-------|
| Backgrounds | `surface_base`, `surface_subtle`, `surface_default`, `surface_elevated`, `surface_highest` |
| Borders | `border_default`, `border_subtle`, `border_active`, `border_emphasis` |
| Controls | `control_active`, `control_inactive`, `control_knob_active`, `control_knob_inactive` |
| Text | `text_primary`, `text_secondary`, `text_subtle`, `text_faint` |
| Accent | `icon_brand`, `logo_brand`, `status_success`, `status_danger` |
| Chat | `chat_prefix`, `chat_body` |
| Effects | `window_shadow`, `scrim`, `selection_highlight`, `overlay_hairline` |

## Example

```lua
module:event("render_2d", function(render)
    render.rect(8, 8, 120, 24, render.paint(theme.color("surface_elevated")), 7)
    render.text("kawaki", 16, 14, 9, render.paint(theme.color("text_primary")))
end)
```

Recolor the accent of the active custom theme:

```lua
theme.set_colors({
    icon_brand = 0xFF967AD8,
    chat_prefix = 0xFF967AD8,
    control_active = 0xFF967AD8,
})
```