Advanced Theming

Advanced theming in FUTO Keyboard allows much greater customization of how the keyboard appears. Currently, this feature is in preview and things may change, but best efforts for backwards-compatibility will be made where possible.

This feature is only available in FUTO Keyboard v0.1.30+

Distinction from simple theming

This is different from simple theming, which is done with the in-app theme editor. Simple theming only allows changing the following attributes:

• Background image, blur, cropping, opacity
• Light or dark
• Primary color hue, saturation, and contrast
• Key borders on/off

Simple theming is simple to use and is accessible from FUTO Keyboard Settings > Themes. It does not require anything more than selecting a background image.

Advanced theming is more advanced and requires using the web-based theme editor (not compatible with mobile) or manually editing the TOML file (not recommended). It allows changing:

• All 44 colors used in the keyboard and app
• Replacing key icons, such as the shift and enter keys
• Changing key roundedness
• Centering the hints
• Changing the keyboard font, text scale and weight
• Replacing key borders with nine-slice assets via matchrule system

Advanced theme editor usage

Access the theme editor at https://keyboard.futo.tech/theme-editor

First, create a new project: File > New / open project… > Blank project

Some usage details are available in Help > About

Import the christmas theme via File > Import theme to see an example of a real theme, using advanced matchrules for variance and correct usage of nine-slicing for its borders.

theme.txt for advanced themes

The advanced theme editor linked above already handles all of this for you. If you’re editing by hand, keep in mind the theme.txt should include the following:

• # Format version: 1.0 somewhere near the top
• A name field containing a human-readable name
• A description field containing any information about your theme.
• An author field
• An id field, which should be globally unique. Consider using your name or domain here. A common alternative is also to use your GitHub username since everyone gets a GitHub pages domain from that. Example: io.github.myusername.MyTheme. If you have no domain whatsoever, just use i.myname.MyTheme
• A version field, which should be an integer. Any updates to your theme should increment this number.

There are more fields. A full example:

# Format version: 1.0
name = "My Theme"
author = "My Name"
id = "com.example.MyTheme"
version = 1
description = "This is my awesome theme :)"

[options]
auto_borders = true
center_hints = false
scale_text = 1
scale_hints = 1
weight_text = 400
weight_hints = 500

[colors]
primary = "#ff3c3c"
on_primary = "#410003"
primary_container = "#ffdad6" 
on_primary_container = "#2a1614" 
inverse_primary = "#ffb3ac" 

secondary = "#b60075" 
on_secondary = "#ffffff" 
secondary_container = "#ffd8e6" 
on_secondary_container = "#2b151f" 

tertiary = "#5e2aff" 
on_tertiary = "#ffffff" 
tertiary_container = "#e6deff" 
on_tertiary_container = "#1c1830" 

background = "#f9f9f9" 
on_background = "#1a1c1c" 

surface = "#f9f9f9" 
on_surface = "#1a1c1c" 
surface_variant = "#dde4e6" 
on_surface_variant = "#41484a" 
surface_tint = "#ff3c3c" 
inverse_surface = "#2f3131" 
inverse_on_surface = "#f1f1f1" 

error = "#c00100" 
on_error = "#ffffff" 
error_container = "#ffdad4" 
on_error_container = "#2a1613" 

outline = "#767777cc" 
outline_variant = "#c6c6c766" 
scrim = "#000000" 

surface_bright = "#f9f9f9" 
surface_dim = "#dadada" 
surface_container = "#edeeee" 
surface_container_high = "#e7e8e8" 
surface_container_highest = "#e2e3e3" 
surface_container_low = "#f3f4f4" 
surface_container_lowest = "#ffffff" 

keyboard_surface = "#ffffff"
keyboard_surface_dim = "#e2e3e3" 
keyboard_container = "#89510b"
keyboard_container_variant = "#7a4600" 
on_keyboard_container = "#ffdcbe" 
keyboard_press = "#ad3522"
keyboard_container_pressed = "#76777754" 
on_keyboard_container_pressed = "#76777700" 

[options.font]
font = "MyFont.ttf"

[options.background]
image = "MyBackground.webp"
opacity = 1
action_bar_opacity = 0.5
cropping = [0, 0, 1, 1]

Rather than editing by hand, it’s recommended to use the theme editor.