# theme/themes (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/theme/themes.ts](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts).

## Functions

### `resolveTheme`

Function.

Finds a theme by id.

```ts
function resolveTheme(id: string | undefined, extraThemes?: readonly Theme[]): Theme
```

**Parameters**

- `id` (`string | undefined`): The theme id. May be `undefined`.
- `extraThemes?` (`readonly Theme[]`, default `[]`): Extension themes, checked before the built-in ones.

**Returns** `Theme`: The matching theme, or [`DEFAULT_THEME`](https://zidane.si/docs/reference/ui-theme-themes.md#DEFAULT_THEME) when the id is missing or unknown.

Source: [ui/src/theme/themes.ts:754](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L754)

## Constants

### `BUILTIN_THEMES`

Constant.

The built-in themes by id. Insertion order is the picker cycle order: `default` first, then
light, then the dark and light families.

```ts
const BUILTIN_THEMES: Readonly<Record<string, Theme>>
```

Source: [ui/src/theme/themes.ts:734](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L734)

### `DEFAULT_THEME`

Constant.

The default dark theme, used when an id is unknown.

```ts
const DEFAULT_THEME: Theme
```

Source: [ui/src/theme/themes.ts:172](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L172)

## Interfaces

### `SyntaxTokenStyle`

Interface.

Style of one syntax token: colours and font emphasis.

```ts
interface SyntaxTokenStyle
```

**Properties**

- `bg?` (`string`): Background colour.
- `bold?` (`boolean`): Draw the token in bold.
- `fg?` (`string`): Text colour.
- `italic?` (`boolean`): Draw the token in italic.
- `underline?` (`boolean`): Draw the token underlined.

Source: [ui/src/theme/themes.ts:92](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L92)

### `Theme`

Interface.

A colour theme: its identity, palette, selection colours, surfaces and syntax styles. It
parallels the terminal UI's themes but keeps only what the GUI reads.

```ts
interface Theme
```

**Properties**

- `colors` (`ThemeColors`): The theme's palette.
- `id` (`string`): Unique id, such as `default` or `light`. It is what [`resolveTheme`](https://zidane.si/docs/reference/ui-theme-themes.md#resolveTheme) looks up.
- `label` (`string`): Name shown in the theme picker.
- `select` (`ThemeSelect`): Colours of selectable option lists.
- `surfaces` (`ThemeSurfaces`): Surface, selection, chip and diff colours.
- `syntax` (`SyntaxStyles`): Syntax token styles.

Source: [ui/src/theme/themes.ts:115](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L115)

### `ThemeColors`

Interface.

GUI theme registry. Spiritually parallel to the canonical TUI themes
in `zidane/src/chat/themes/*` but decoupled — the renderer only
consumes a narrow subset (palette, surfaces and `syntax.default.fg`),
so we keep the shape local and avoid lockstepping with canonical
theme-type churn (which carries TUI-only fields the GUI never reads).

GUI-only color slots that aren't in the TUI palette:

- `throbber: [from, to]` — Throbber gradient endpoints; defaults to
  `brand` and a muted `accent` when omitted.
- `money: string` — footer cost-pill tint; defaults to `--zg-text-muted`
  when omitted.

```ts
interface ThemeColors
```

**Properties**

- `accent` (`string`): Secondary hue, usually a success green. It becomes the palette's `accentAlt`.
- `border` (`string`): Default border colour.
- `borderActive` (`string`): Border colour of the focused or active element. It becomes the palette's focus `ring`.
- `brand` (`string`): Brand and interactive colour. It becomes the palette's `accent`.
- `dim` (`string`): Secondary text colour. It becomes the palette's `textMuted`.
- `error` (`string`): Error status colour. It becomes the palette's `danger`.
- `model` (`string`): Tint that identifies the model.
- `money?` (`string`): Tint of the footer cost figure. Defaults to the muted text colour.
- `mute` (`string`): Tertiary text colour. It becomes the palette's `textSubtle`.
- `throbber?` (`readonly [string, string]`): The two colours of the busy indicator. Defaults to `brand` and `accent`.
- `warn` (`string`): Warning status colour.

Source: [ui/src/theme/themes.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L16)

### `ThemeDiff`

Interface.

Colours of a diff in a theme.

```ts
interface ThemeDiff
```

**Properties**

- `addBg` (`string`): Background of an added line.
- `addContentBg?` (`string`): Stronger background behind the changed text inside an added line. Derived when omitted.
- `addFg` (`string`): Text colour of an added line.
- `removeBg` (`string`): Background of a removed line.
- `removeContentBg?` (`string`): Stronger background behind the changed text inside a removed line. Derived when omitted.
- `removeFg` (`string`): Text colour of a removed line.

Source: [ui/src/theme/themes.ts:60](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L60)

### `ThemeSelect`

Interface.

Colours of a list of selectable options, in the shape the terminal themes use.

```ts
interface ThemeSelect
```

**Properties**

- `backgroundColor` (`string`): Background of an option.
- `descriptionColor` (`string`): Colour of an option's description.
- `focusedBackgroundColor` (`string`): Background of the focused option.
- `selectedBackgroundColor` (`string`): Background of the selected option.
- `selectedDescriptionColor` (`string`): Colour of the selected option's description.
- `selectedTextColor` (`string`): Text colour of the selected option.
- `textColor` (`string`): Text colour of an option.

Source: [ui/src/theme/themes.ts:42](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L42)

### `ThemeSurfaces`

Interface.

Surface colours of a theme: the window canvas, reference chips, selection and diffs.

```ts
interface ThemeSurfaces
```

**Properties**

- `chips` (`{ default: { bg: string; fg: string }; files: { bg: string; fg: string }; skills: { bg: string; fg: string } }`): Background and text colour of each kind of reference chip.
- `diff` (`ThemeDiff`): Diff colours.
- `modal` (`string`): Background of the window and modal layers. It becomes the palette's canvas.
- `selection` (`string`): Text selection background.

Source: [ui/src/theme/themes.ts:76](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L76)

## Types

### `SyntaxStyles`

Type.

Styles of syntax tokens by token name. The `default` entry's `fg` is the palette's body text
colour.

```ts
type SyntaxStyles = Partial<Record<string, SyntaxTokenStyle>>
```

Source: [ui/src/theme/themes.ts:109](https://github.com/Tahul/zidane/blob/main/ui/src/theme/themes.ts#L109)