Theme and units

Note

This page is generated from the doc comments in kiln/ by tools/docgen. Fix the comment, not the page.

At a glance

Color :: clay.Color
Colors :: struct {...}
Flavor :: enum {...}
FontFace :: enum {...}
Metrics :: struct {...}
Radius :: enum {...}
Scale :: struct {...}
Screen :: enum {...}
Size :: enum {...}
Space :: enum {...}
Surface :: enum {...}
TextStyle :: enum {...}
Theme :: struct {...}
Tone :: enum {...}
inset :: proc{inset_all, inset_xy}
by_screen :: proc(compact, medium, expanded: $T) -> T
catppuccin :: proc(flavor: Flavor) -> Theme
catppuccin_colors :: proc(flavor: Flavor) -> Colors
corners :: proc(r: Radius) -> clay.CornerRadius
default_metrics :: proc() -> Metrics
fade :: proc(color: Color, alpha: f32) -> Color
font :: proc(style: TextStyle, color: Color) -> clay.TextElementConfig
font_size :: proc(style: TextStyle) -> u16
inset_all :: proc(s: Space) -> clay.Padding
inset_xy :: proc(x, y: Space) -> clay.Padding
line_width :: proc() -> f32
measure :: proc(text: string, style: TextStyle) -> f32
mix :: proc(a, b: Color, t: f32) -> Color
outline :: proc(color: Color) -> clay.BorderElementConfig
px :: proc(units: f32) -> f32
radius :: proc(r: Radius) -> f32
scale_factor :: proc() -> f32
screen :: proc() -> Screen
set_colors :: proc(c: Colors)
set_metrics :: proc(m: Metrics)
set_theme :: proc(t: Theme)
set_zoom :: proc(zoom: f32)
size :: proc(s: Size) -> f32
space :: proc(s: Space) -> u16
surface_color :: proc(s: Surface) -> Color
theme :: proc() -> Theme
tone_color :: proc(t: Tone) -> Color
tone_tint :: proc(t: Tone) -> Color
window_size :: proc() -> [2]f32
zoom :: proc() -> f32
KILN_EMBED_FONTS :: #config(KILN_EMBED_FONTS, true)

Types

Color

Color :: clay.Color

Source: kiln/theme.odin:13

Colors

Colors :: struct {
  window, sunken:                         Color, // window background / inset areas (inputs, sidebars)
  surface, surface_hover, surface_active: Color, // raised areas (cards, buttons) and their hover / pressed shade
  border, border_strong:                  Color,
  text, text_muted, text_faint:           Color,
  primary, on_primary:                    Color, // on_primary: text drawn on any accent color
  info, success, warning, danger:         Color,
  selection:                              Color, // text selection (semi-transparent)
  chart:                                  [8]Color, // categorical colors for charts, see `chart_color`
}

Color slots used by all widgets.

Field	Type	Notes
window	Color	window background / inset areas (inputs, sidebars)
sunken	Color	window background / inset areas (inputs, sidebars)
surface	Color	raised areas (cards, buttons) and their hover / pressed shade
surface_hover	Color	raised areas (cards, buttons) and their hover / pressed shade
surface_active	Color	raised areas (cards, buttons) and their hover / pressed shade
border	Color
border_strong	Color
text	Color
text_muted	Color
text_faint	Color
primary	Color	on_primary: text drawn on any accent color
on_primary	Color	on_primary: text drawn on any accent color
info	Color
success	Color
warning	Color
danger	Color
selection	Color	text selection (semi-transparent)
chart	[8]Color	categorical colors for charts, see chart_color

Source: kiln/theme.odin:16

Flavor

Flavor :: enum {
  Mocha,
  Macchiato,
  Frappe,
  Latte,
}

Catppuccin color schemes. Mocha, Macchiato and Frappe are dark, Latte is light.

Values: .Mocha, .Macchiato, .Frappe, .Latte

Source: kiln/catppuccin.odin:4

FontFace

FontFace :: enum {
  Regular,
  Bold,
}

Values: .Regular, .Bold

Source: kiln/theme.odin:89

Metrics

Metrics :: struct {
  spacing:        [Space]f32,
  radii:          [Radius]f32, // `.Full` is not scaled
  sizes:          [Size]f32,
  breakpoints:    [Screen]f32, // minimum window width of each screen class
  border_width:   f32,
  font_base:      f32, // font size of `.Body`
  font_ratio:     f32, // factor between two neighbouring text styles
  font_faces:     [TextStyle]FontFace,
  font_files:     [FontFace]cstring, // paths, relative to the working directory
  font_data:      [FontFace][]u8, // font files in memory (e.g. `#load`ed); win over `font_files`
  font_fallbacks: [][]u8, // fonts in memory for characters the faces lack (CJK, symbols, ...), tried in order
  anim_speed:     f32, // rate per second of hover / toggle fades
  tooltip_delay:  f32, // seconds of hover before a tooltip shows
  toast_duration: f32, // seconds a toast stays visible
  spinner_speed:  f32, // spinner pulses per second
  tint_alpha:     f32, // opacity of tinted backgrounds (badges, selected items)
  backdrop_alpha: f32, // opacity of the dialog / drawer backdrop
  stripe_alpha:   f32, // opacity of the zebra stripes in tables
  locale:         Locale, // month / weekday names for calendars (`locale_en`, `locale_de`)
}

All dimensions of the UI in units. The UI scale (DPI, zoom) turns units into pixels.

Field	Type	Notes
spacing	[Space]f32
radii	[Radius]f32	.Full is not scaled
sizes	[Size]f32
breakpoints	[Screen]f32	minimum window width of each screen class
border_width	f32
font_base	f32	font size of .Body
font_ratio	f32	factor between two neighbouring text styles
font_faces	[TextStyle]FontFace
font_files	[FontFace]cstring	paths, relative to the working directory
font_data	[FontFace][]u8	font files in memory (e.g. #loaded); win over font_files
font_fallbacks	[][]u8	fonts in memory for characters the faces lack (CJK, symbols, …), tried in order
anim_speed	f32	rate per second of hover / toggle fades
tooltip_delay	f32	seconds of hover before a tooltip shows
toast_duration	f32	seconds a toast stays visible
spinner_speed	f32	spinner pulses per second
tint_alpha	f32	opacity of tinted backgrounds (badges, selected items)
backdrop_alpha	f32	opacity of the dialog / drawer backdrop
stripe_alpha	f32	opacity of the zebra stripes in tables
locale	Locale	month / weekday names for calendars (locale_en, locale_de)

Source: kiln/theme.odin:95

Radius

Radius :: enum {
  None,
  SM,
  MD,
  LG,
  Full,
}

Named corner radius steps. .Full gives pills and circles.

Values: .None, .SM, .MD, .LG, .Full

Source: kiln/theme.odin:58

Scale

Scale :: struct {
  zoom:       f32, // manual zoom factor (0 = 1), also changed with Ctrl +/-/0
  fit_height: f32, // if > 0, scale with the window height relative to this many units
  ignore_dpi: bool, // do not multiply by the monitor's DPI scale
}

How the UI scales with the window.

Field	Type	Notes
zoom	f32	manual zoom factor (0 = 1), also changed with Ctrl +/-/0
fit_height	f32	if > 0, scale with the window height relative to this many units
ignore_dpi	bool	do not multiply by the monitor’s DPI scale

Source: kiln/units.odin:12

Screen

Screen :: enum {
  Compact, // phones, very narrow windows
  Medium, // tablets, half-screen windows
  Expanded, // desktop windows
}

Window size classes, see Metrics.breakpoints.

Values: .Compact, .Medium, .Expanded

Source: kiln/units.odin:19

Size

Size :: enum {
  Track, // slider track thickness
  Bar, // progress bar thickness
  Dot, // badge dot, spinner dots
  Mark, // checkbox / radio box, slider knob, tree indent
  Control, // height of buttons, inputs, selects
  Avatar,
  Drawer,
  Dialog, // maximum dialog width
  Menu, // minimum menu width
  Toast,
}

Named element sizes.

Values: .Track, .Bar, .Dot, .Mark, .Control, .Avatar, .Drawer, .Dialog, .Menu, .Toast

Source: kiln/theme.odin:67

Space

Space :: enum {
  None,
  XS,
  SM,
  MD,
  LG,
  XL,
}

Named spacing steps (padding, gaps).

Values: .None, .XS, .SM, .MD, .LG, .XL

Source: kiln/theme.odin:48

Surface

Surface :: enum {
  None, // transparent
  Window,
  Sunken,
  Raised,
}

Background slots for containers.

Values: .None, .Window, .Sunken, .Raised

Source: kiln/theme.odin:28

TextStyle

TextStyle :: enum {
  Caption,
  Body,
  Subtitle,
  Title,
  Headline,
}

Typographic styles, from small to large.

Values: .Caption, .Body, .Subtitle, .Title, .Headline

Source: kiln/theme.odin:81

Theme

Theme :: struct {
  using colors:  Colors,
  using metrics: Metrics,
}

Colors and metrics. Fields of both parts can be accessed directly: t.primary, t.radii[.MD].

Field	Type	Notes
using colors	Colors
using metrics	Metrics

Source: kiln/theme.odin:118

Tone

Tone :: enum {
  Default,
  Muted,
  Faint,
  Primary,
  Info,
  Success,
  Warning,
  Danger,
}

Semantic colors for text, badges, progress bars and toasts.

Values: .Default, .Muted, .Faint, .Primary, .Info, .Success, .Warning, .Danger

Source: kiln/theme.odin:36

Procedure groups

inset

inset :: proc{inset_all, inset_xy}

Padding from spacing steps: inset(.MD) on all sides, inset(.LG, .SM) horizontal / vertical.

Calls one of these, depending on the argument types:

• inset_all proc(s: Space) -> clay.Padding
• inset_xy proc(x, y: Space) -> clay.Padding

Source: kiln/units.odin:111

Procedures

by_screen

by_screen :: proc(compact, medium, expanded: $T) -> T

Picks the value for the current screen class:

columns := kiln.by_screen(1, 2, 4)

Argument	Type	Default
compact	T	required
medium	T	required
expanded	$T	required

Returns	Type
#0	T

Source: kiln/units.odin:84

catppuccin

catppuccin :: proc(flavor: Flavor) -> Theme

A complete theme from a Catppuccin flavor and the default metrics.

Argument	Type	Default
flavor	Flavor	required

Returns	Type
#0	Theme

Source: kiln/catppuccin.odin:124

catppuccin_colors

catppuccin_colors :: proc(flavor: Flavor) -> Colors

Argument	Type	Default
flavor	Flavor	required

Returns	Type
#0	Colors

Source: kiln/catppuccin.odin:99

corners

corners :: proc(r: Radius) -> clay.CornerRadius

Argument	Type	Default
r	Radius	required

Returns	Type
#0	clay.CornerRadius

Source: kiln/units.odin:132

default_metrics

default_metrics :: proc() -> Metrics

4px based spacing, 36px controls, 16px body text, Iosevka.

Returns	Type
#0	Metrics

Source: kiln/theme.odin:140

fade

fade :: proc(color: Color, alpha: f32) -> Color

color with its alpha replaced by alpha (0..1).

Argument	Type	Default
color	Color	required
alpha	f32	required

Returns	Type
#0	Color

Source: kiln/theme.odin:209

font

font :: proc(style: TextStyle, color: Color) -> clay.TextElementConfig

Clay text config for a style and color.

Argument	Type	Default
style	TextStyle	required
color	Color	required

Returns	Type
#0	clay.TextElementConfig

Source: kiln/units.odin:161

font_size

font_size :: proc(style: TextStyle) -> u16

Font size of a text style in pixels: font_base * font_ratio^(style - Body).

Argument	Type	Default
style	TextStyle	required

Returns	Type
#0	u16

Source: kiln/units.odin:154

inset_all

inset_all :: proc(s: Space) -> clay.Padding

Argument	Type	Default
s	Space	required

Returns	Type
#0	clay.Padding

Source: kiln/units.odin:116

inset_xy

inset_xy :: proc(x, y: Space) -> clay.Padding

Argument	Type	Default
x	Space	required
y	Space	required

Returns	Type
#0	clay.Padding

Source: kiln/units.odin:121

line_width

line_width :: proc() -> f32

The theme’s border width in pixels (at least 1 if the theme has borders).

Returns	Type
#0	f32

Source: kiln/units.odin:142

measure

measure :: proc(text: string, style: TextStyle) -> f32

Width of text in pixels when set in style.

Argument	Type	Default
text	string	required
style	TextStyle	required

Returns	Type
#0	f32

Source: kiln/units.odin:166

mix

mix :: proc(a, b: Color, t: f32) -> Color

Interpolates all channels (including alpha) from a to b by t (0..1).

Argument	Type	Default
a	Color	required
b	Color	required
t	f32	required

Returns	Type
#0	Color

Source: kiln/theme.odin:204

outline

outline :: proc(color: Color) -> clay.BorderElementConfig

A border of the theme’s width around an element.

Argument	Type	Default
color	Color	required

Returns	Type
#0	clay.BorderElementConfig

Source: kiln/units.odin:149

px

px :: proc(units: f32) -> f32

Units to pixels (rounded).

Argument	Type	Default
units	f32	required

Returns	Type
#0	f32

Source: kiln/units.odin:101

radius

radius :: proc(r: Radius) -> f32

A corner radius in pixels. .Full is not scaled.

Argument	Type	Default
r	Radius	required

Returns	Type
#0	f32

Source: kiln/units.odin:127

scale_factor

scale_factor :: proc() -> f32

Pixels per unit in the current frame.

Returns	Type
#0	f32

Source: kiln/units.odin:46

screen

screen :: proc() -> Screen

The size class of the window.

Returns	Type
#0	Screen

Source: kiln/units.odin:74

set_colors

set_colors :: proc(c: Colors)

Replaces only the colors, e.g. to switch between a dark and a light scheme.

Argument	Type	Default
c	Colors	required

Source: kiln/theme.odin:194

set_metrics

set_metrics :: proc(m: Metrics)

Replaces only the metrics, e.g. for a compact or a rounded look.

Argument	Type	Default
m	Metrics	required

Source: kiln/theme.odin:199

set_theme

set_theme :: proc(t: Theme)

Replaces colors and metrics. Font changes reload the fonts at the start of the next frame.

Argument	Type	Default
t	Theme	required

Source: kiln/theme.odin:189

set_zoom

set_zoom :: proc(zoom: f32)

Argument	Type	Default
zoom	f32	required

Source: kiln/units.odin:37

size

size :: proc(s: Size) -> f32

An element size in pixels.

Argument	Type	Default
s	Size	required

Returns	Type
#0	f32

Source: kiln/units.odin:137

space

space :: proc(s: Space) -> u16

A spacing step in pixels, as Clay expects it for gaps.

Argument	Type	Default
s	Space	required

Returns	Type
#0	u16

Source: kiln/units.odin:106

surface_color

surface_color :: proc(s: Surface) -> Color

Argument	Type	Default
s	Surface	required

Returns	Type
#0	Color

Source: kiln/theme.odin:249

theme

theme :: proc() -> Theme

A copy of the active theme, e.g. to derive a modified one.

Returns	Type
#0	Theme

Source: kiln/theme.odin:184

tone_color

tone_color :: proc(t: Tone) -> Color

The theme color of a tone (as text / foreground color).

Argument	Type	Default
t	Tone	required

Returns	Type
#0	Color

Source: kiln/theme.odin:216

tone_tint

tone_tint :: proc(t: Tone) -> Color

Tinted background for a tone (badges, selected rows, toasts).

Argument	Type	Default
t	Tone	required

Returns	Type
#0	Color

Source: kiln/theme.odin:240

window_size

window_size :: proc() -> [2]f32

Window size in units.

Returns	Type
#0	[2]f32

Source: kiln/units.odin:69

zoom

zoom :: proc() -> f32

Returns	Type
#0	f32

Source: kiln/units.odin:41

Constants

KILN_EMBED_FONTS

KILN_EMBED_FONTS :: #config(KILN_EMBED_FONTS, true)

The Iosevka subsets in resources/ are compiled into the binary, so apps start from any directory. Build with -define:KILN_EMBED_FONTS=false to load font_files at runtime instead (see tools/subset_font for making subsets of other fonts).

Source: kiln/theme.odin:126