# ADR-0024: Themes are semantic-role data files

- **Status:** Accepted; amended by 0142
- **Date:** 2026-06-25
- **Deciders:** jka
- **Decision:** D24

## Context

The GUI should be themeable, with live switching and different typography for the
code surface and the chat. Themes that name widget paths break whenever the widget
tree changes, and themes written as Tcl scripts would execute code.

## Decision

A theme is a data file in the configuration format of ADR-0021, parsed and never
executed. It names **semantic roles**, not widgets:

- **Colours by role**, for example `editor.bg`, `editor.fg`, `editor.selection`,
  `ui.bg`, `tab.active.bg`, `gutter.fg`, `chat.bg`, `accent`. Two themes differ only
  in values.
- **Fonts by role**, through Tk named fonts (`RioEditorFont`, `RioUIFont`,
  `RioChatFont`). Reconfiguring a named font updates every widget that uses it,
  so size and theme changes need no restart.

A theme may declare `base = <theme>` and override a subset of roles. The core
serves the merged role table (`theme.get`); a small applier in the GUI maps it
onto Tk. The default theme is the plain white background and black text. Later
decisions added roles rather than hard-coded colours: `error`, the diff roles,
`syntax.*` (ADR-0032), `editor.findmatch` (ADR-0036) and `editor.currentline`
(ADR-0060). A theme that omits a role inherits the default.

## Consequences

- A new theme is a set of values, and theme files cannot break or compromise rio.
- The colour-role vocabulary is shared, so a future TUI can map the same roles onto
  a terminal palette.
- The Tk-specific mapping lives in one applier in the GUI.
- Tooltips are the one deliberate exception and ignore the theme (ADR-0063).