Reference

Themes

This page tells how to pick the colors of Tiza and how to change one color. It covers the built-in themes, the auto theme, the terminal theme, the color tokens and the theme of each export.

Pick a theme

Tiza has two built-in themes, dark and light. It also has a terminal theme that uses the colors of your terminal.

When you pick a theme, Tiza stops following the terminal. Tiza keeps the theme in the document, and the next save writes it. Then the next session opens with the same theme. t and --theme do not save the document. See Themes and saving.

The auto theme

A document that names no theme follows the terminal. This is the auto theme. When Tiza starts, it sends the color query to ask the terminal for its background color. A light background gives the light theme, and a dark background gives dark. The status bar shows light·auto or dark·auto.

• When the terminal sends no answer for 100 ms, Tiza stops waiting. It shows no message. A document that names no theme then gets dark.
• A pseudo-terminal with no terminal program behind it is an example of a terminal that sends no answer.
• When the variable TIZA_NO_OSC is set, also to an empty value, Tiza does not send the color query. This applies at start and at each resize.
• With --theme auto, a document that names a theme keeps that theme until the terminal answers.
• :theme auto sends no color query. It uses the last answer of the terminal. With no answer yet, it keeps the theme on screen until an answer comes.
• Tiza keeps the keys that you type while it waits. For example, nn right after tiza FILE --present moves two steps.
• Tiza sends the color query again at each resize of the terminal.
• When the theme of your terminal changes with no resize, type kill -WINCH $(pgrep tiza) in another shell. Tiza then sends the color query again. Terminal support tells what each tmux version does with the color query.
• These stop the auto theme: t, :theme NAME, --theme NAME, a document that names a theme, and an agent that sets a fixed theme.
• :theme auto starts the auto theme again. Then the document names no theme.

Use the terminal colors

:theme terminal and --theme terminal draw Tiza with the palette of your terminal. The background and the text use the default colors of the terminal. The other tokens use the 16 ANSI colors of the terminal. The syntax uses the colors of the terminal too. Then Tiza looks like the rest of your terminal.

• Tiza does not pick the terminal theme by itself. When the terminal answers, the auto theme picks dark or light.
• The tokens of the terminal theme send no 24-bit color. Use the theme in a terminal that has no 24-bit color.
• The tokens of the config file and of the document apply to the terminal theme too. Tiza sends a token in #rrggbb, #rgb or rgb() form as a 24-bit color. It does the same with an annotation color in #rrggbb form.
• The terminal theme picks the tint of a highlight and of the status bar from the answer. A dark terminal gets ANSI color 8, and a light terminal gets ANSI color 7.
• t goes from terminal to the built-in theme that matches the background of the terminal. With no answer, t goes to dark.
• An export cannot use the palette of the terminal. See Exports.

Change a color

Each color of a theme has a name: its token. You can give a token a new value in a theme file, in the config file or in the document.

1. Write a TOML file with the tokens that you want to change. For example, my-theme.toml:

   accent = "#fab387"
   note = "#f9e2af"
   blue = "#89b4fa"

2. In Tiza, type :theme file my-theme.toml. Or start Tiza with tiza FILE --theme-file my-theme.toml.

3. Tiza puts the tokens in the document, in the field theme_overrides. With autosave on, Tiza saves them at once. :export and export_image use them at once. tiza render and the next session use them after the save.

• A theme file replaces all the tokens that the document had. It does not add to them.
• Press u to undo :theme file. Press U or Ctrl-R to do it again.
• u does not undo --theme-file, as for --theme.
• --theme-file writes the tokens in the document when Tiza starts. With --no-save, Tiza does not write them to the .tiza file.
• To use the same tokens in each document, put them in the [theme] table of the config file. See Where the tokens go.
• tiza render FILE --theme-file PATH uses the file for one export, in place of the tokens of the document. It does not change the document.
• The Catppuccin Mocha example is the file to copy. It sets the tokens of Tiza to the published Catppuccin Mocha colors. It passes the legibility check. See Legibility.
• No token sets a color of the syntax, such as the color of a keyword.

For example, load the Catppuccin Mocha example, a copy of examples/themes/catppuccin-mocha.toml, and highlight &t. The image is a real tiza render export with the tokens of the document:

examples/ownership.rs, lines 6 to 8

:theme file catppuccin-mocha.toml
:hl 7:&t shared borrow

Put ownership.rs and catppuccin-mocha.toml in one folder. In that folder, run tiza ownership.rs:6-8 --no-save. Then type the commands.

Theme names

• :theme without a name, and :theme toggle, change the theme as t does. Unlike t, they save the document when autosave is on.
• :t is the short form of :theme.
• --theme and tiza render --theme take only dark, light, terminal and auto.
• theme.set and set_theme take the names and the aliases of the table, except host.
• :export theme= and export_image take only dark, light, oscuro and claro.

Presentation mode hides the status bar.

Color tokens

The table lists each token that you can set, with its main use.

• In dark and light, orange is the accent color and gray is the muted color, until you set them.
• An arrow without a color takes the next color of this list: orange, blue, green, purple, cyan, pink, yellow. To change the color of these arrows, set these tokens.
• In the terminal theme, highlight_bg is also the tint of a selection and of a mark. This is also so in dark or light when bg or the mark color is a color of the terminal palette.
• An export message can name rail, box_bg or arrow when one of them has an ANSI color or reset.

Color values

• An ANSI name, for example red or bright-blue. It gives a color of the terminal palette. The ANSI names are black, red, green, yellow, blue, magenta, cyan and white. Add bright- before a name for its bright color. brightblue with no dash also works.
• default and none are the same as reset.
• A color name of an annotation, such as orange, is not a color value. red, blue and the other names that are also ANSI names give the colors of the terminal.
• Tiza ignores the case and the spaces around a value. A token name must be in lower case: Accent is an unknown token.
• An ANSI color and reset have no value in an export. See Exports.

Where the tokens go

For example, this config file sets a different accent on dark and on light:

[theme.dark]
accent = "#a6e3a1"

[theme.light]
accent = "#b7410e"

• A subtable applies only when its theme is in use.
• When a token is both in a table and in its subtable, the subtable wins while its theme is in use.
• Tiza applies the tokens in this order, and the last one wins: the built-in theme, the config file, the document.
• :theme NAME and t change the base theme. The tokens stay and apply on the new theme.
• When a theme file has a [theme] table, Tiza ignores the keys outside it. It does not report them.

Wrong tokens and values

• In the config file and in a theme file, Tiza ignores an unknown token, an unknown subtable, a value that is not a string and a color that it cannot read. It applies the other tokens.
• Tiza reports a value that is not a string in every subtable. It does not report a color that it cannot read in the subtable of a theme that is not in use.
• A theme file does not load when Tiza cannot read it, when its TOML is not valid, or when it has no color token to apply. An empty file and a file where no value is a string have none.
• Then :theme file shows the error and changes nothing. --theme-file shows the error, and Tiza starts without the file. tiza render exits with 1.
• For the config file, Tiza writes a warning for each value that it leaves out. See Warnings of the config file.
• In the theme_overrides of a document, a value that is not a string stops the document from opening. Then Tiza writes tiza: could not open FILE and exits with 1.

The config file

The [theme] table of the config file holds your own tokens for every session. Where Tiza finds the file, when it reads the file, and its other tables are in Config file.

Messages

• In theme file PATH: N token(s) applied on NAME, N counts the keys at the top of the file. A subtable counts as one key, and an unknown key counts too. A value that is not a string does not count.
• When Tiza cannot read a theme file, or its TOML is not valid, the message is PATH: and the error text.
• After no color token to apply, the message gives the reports of the values that Tiza left out.
• The other warnings of the config file are in Warnings of the config file.
• tiza: could not open FILE ends with the error text of the JSON reader. For a value in theme_overrides that is not a string, that text says expected a color string or a table of color strings.
• For a wrong # or rgb() value, the text after VALUE: tells what is wrong.
• :export adds an export message after —. tiza render writes it on stderr. export_image does not show it.

When Tiza shows the token reports

The token reports are the messages about an unknown token, an unknown table, a wrong value and a faint token.

• The TUI shows them after :theme, :theme NAME, :theme toggle, :theme file and --theme-file. It adds each one after the message, after ; .
• At start, the status bar shows the first warning of the config file and the number of warnings that tiza config lists. The token reports of [theme] in the config file count as warnings. The TUI does not show the token reports of the document at start. Only --theme-file shows reports at start.
• The TUI shows no reports after t, after :theme auto or after a change from an agent.
• tiza render writes each report on its own line on stderr, after tiza: .
• export_image shows no token report. In warning, it says what the config file left out, or that Tiza cannot read the config file.

Exports

An export cannot use the palette of the terminal. Each export picks its theme as this table shows. The Tokens column is for dark and light.

• :export exports light when the auto theme shows light. tiza render and export_image cannot ask the terminal. They export a document that follows the terminal as dark.
• tiza render --theme auto uses the theme of the document, else dark.
• tiza render --theme terminal exports dark, and writes the message about the terminal theme on stderr.
• With the terminal theme, :export uses the built-in theme that matches the background of the terminal. With no answer, it uses dark. tiza render and export_image always use dark.
• An export of the terminal theme uses the plain dark or light theme. No token applies: not the config file, the document, --theme-file or [theme.terminal].
• In an export of dark or light, a token with an ANSI color or reset takes the color of the built-in theme.

Themes and saving

• With autosave on, these save the document at once: :theme with or without a name, :theme file, theme.set, set_theme, and a scene patch with theme. See Saving.
• t, --theme NAME and --theme auto change the theme of the document, but do not save it. The next save writes the change.
• When you quit after t with no other change, the document keeps its old theme.
• --theme-file saves the document when Tiza starts, except with --no-save.
• The document keeps a theme only when the theme is fixed. A document that follows the terminal has no theme field.

Agents and themes

• set_theme (MCP) and theme.set (socket) take dark, light, terminal, auto or toggle. They also take the aliases oscuro, claro, term and ansi.
• With no theme, or an empty one, theme.set changes between dark and light as t does.
• The reply has the field auto. It tells whether the instance follows the terminal.
• A scene patch or a scene put with theme sets a fixed theme, as :theme NAME does.
• Under :supervise, a theme.set waits for the presenter. The presenter can reject it. With no decision for 60 s, it fails.
• export_image picks its theme as Exports tells.

How it works

The color query asks the terminal with OSC 11 for the background and with OSC 10 for the text. It sends them as plain OSC, not wrapped for tmux. A background is dark when 0.299 R + 0.587 G + 0.114 B is less than half of 255.

• Tiza sends the color query only with the auto theme or the terminal theme. It sends it at start and at each resize.
• Tiza uses the answer to OSC 10 only to stop waiting early. No color of Tiza comes from it.
• At start, Tiza reads the answer before its input library reads the terminal. It gives the other keys that it read to the editor, in order.
• After start, the answer comes in as key presses. Tiza takes it out of the keys.
• Tiza does not turn on mode 2031, in which the terminal reports a change of its colors. The input library would read that report as key presses.

Legibility

The built-in themes use RGB colors that stay legible in a 1080p video. CI runs scripts/legibility.py on the last step of examples/ownership.rs.tiza, in dark and in light. The script renders a PNG and scales it to 1920×1080. Then it compresses the frame as YouTube does.

• The script measures the text colors of the SVG export against the background.
• It skips a color under 1.5:1 before the compression, because such a color is a tint, not text.
• It skips a color that fills fewer than 40 pixels of the frame.
• Each color that it measures must keep a contrast of 4.5:1 or more. Otherwise the script exits with 1.

To check a theme file, run the script with --theme-file:

python3 scripts/legibility.py examples/ownership.rs.tiza --step 6 --theme-file examples/themes/catppuccin-mocha.toml

The script needs Python with Pillow and numpy, and ffmpeg. It runs target/debug/tiza, or the binary that --bin or TIZA_BIN names. Without ffmpeg, it exits with 2.

Tiza also keeps text legible when it applies tokens:

• It checks fg, muted, accent, note and error against bg. Tiza reports each token that it changes.
• A token under 4.5:1 moves toward black or white, whichever contrasts more with bg.
• This rule is not the dark rule of How it works. For example, #7a7a7a is a dark background by that rule, but a faint token on it moves toward black.
• The move can go all the way to black or white. Thus the token always reaches 4.5:1, as the message says.
• When it draws the code, Tiza moves a syntax color under 4.5:1 toward fg.
• Tiza does not check a color of the terminal palette. It checks no token when bg is a color of the terminal palette. It moves no syntax color when bg or fg is a color of the terminal palette.