Skip to content

Themes

The theme is one design document that sets the look of the whole app. It holds the colours, fonts, text sizes, spacing, roundness, shadows and animations, and the default look of every part: checkboxes, buttons, menus, dialogs, toasts, the sidebar and cards.

What works today

The app uses the theme editor of the old app, as it is. The default theme is Sakura.

  • Change a colour, a font or the background in the theme editor. The engine saves it as one change, with Undo, like any other setting.
  • It lands in your folder as Settings/theme.json. So the theme is in your files, and in an export.
  • It survives a restart. Close the app and open it again: your theme is still there.
  • An imported account keeps its theme. The importer brought your old app’s themes in.

Example: you change the accent to a deeper pink. A moment later Settings/theme.json in your folder has the new value, and the app still shows it after a restart.

theme.json holds your themes in the three layers below: palette and fonts, then color, text and scale.space, then parts. The old app’s theme editor still edits them, and nothing is lost either way. An imported account gets its themes in this shape too. A theme file from before this change is read as it is and saved in the new shape at your next theme change.

{
"version": 2,
"themes": [{
"id": "…", "name": "Sunset", "type": "light",
"palette": { "sunset": "#ff7a45" },
"fonts": { "body": "inter", "heading": "fraunces" },
"color": { "accent": "var(--kzx-c-sunset)", "text": "#2a1a14" },
"text": { "body": { "size": 15, "lineHeight": 22 } },
"parts": { "checkbox": { "shape": "round" }, "sidebar": { "accent": "#ff7a45" } },
"moments": { "checkbox.tick": { "effect": "confetti" } }
}],
"preferences": { "mode": "system", "lightThemeId": "…", "darkThemeId": "builtin:default-dark" }
}

The names are the old app’s under new spellings: its primary colour is color.accent, its foreground is color.text, its accent (the hover fill) is color.hover. The full list is in Theme settings.

On top of the theme, these work today:

  • Looks and Skins. Each is a file in Settings/Design/. A Look restyles parts by their name tags; a Skin replaces the inside of a part, such as a card or a checkbox. Each applies to the whole app, a collection, a view, a page or one entry.

  • The design list in Settings → Designs: every design, where it applies, its health and its cost, with an on/off checkbox, Open (JSON, or HTML and CSS for a skin) and Reset with Undo.

  • Design mode: point at any part to see its name tag, click it to style it.

  • The CSS checker and the cost check run on every design, whoever wrote it.

  • What changed, Safe mode and Find the problem, as in Designs keep working.

  • Uploaded pictures. In Open → HTML and CSS, Add a picture stores a PNG, JPEG, GIF, WebP, AVIF or SVG file (checked first) and puts it where your cursor is: <img asset="…"> in a skin, url(asset:…) in CSS. It shows in the desktop app and in a paired browser.

  • Rules that react to a value. A Look’s rules change parts of an entry while a value holds, in the same condition language as card rules and automations:

    "rules": [{ "if": "@Done == true", "parts": { "card": { "style": { "opacity": 0.6 } } } }]
  • Actions on events. A part’s on (or the Look’s own on) runs actions when you click, long press, hover, change a value, or when the part appears or opens:

    "parts": { "card": { "on": { "click": [{ "play": "confetti", "if": "@Done == true" }, { "toast": "Well done!" }] } } }

    A design can play an animation, show a toast in its own words, open the entry, and three things that change your data: set a value, addTag (a tag the field already has) and timer (start or stop). Those three stay off in every design until you allow them for it in Settings → Designs → Actions that change entries, on that device. Only you can add them. While a design has one, the AI, kzx, MCP and other programs can change only how it looks. Your allow holds for the design exactly as you saw it. If anything changes it afterwards (your own edits excepted), its actions go off again and the list says “Changed since you allowed it”. Clicks inside a protected screen never set off a design’s actions. A design never deletes, moves, shares or opens a link.

In the theme editor (Settings → Appearance, then edit a theme):

  • Light and dark. Tick “Different colours in dark mode” (or light mode), then pick which side you edit. The theme then fills both the light and the dark slot and follows your light/dark choice.
  • Size and corners. Text size from 80% to 140%, and corners from Sharp to Very round.
  • Motion. Animations Off, Calm, Normal or Extra, and the effect of each moment: Delete, Restore, Tick, Untick, Create, All done, Timer done, Drop, Error and Page open.

Under a moment that plays confetti you can set how many pieces fly and their colour; a glow takes a colour too. Colours come from the theme (a colour such as primary, or one of your palette colours), so they change with the theme. In the theme JSON: "allDone": { "effect": "confetti", "count": 120, "colors": ["success", "sunset"] }.

To see each effect, open Settings → Appearance → Effects and press Play beside a moment.

Restore plays the delete’s dust in reverse: the grains fly back and the card comes back as they land. Tick and All done can also play Fireworks.

Your effects. Under Motion, press Add an effect to save an effect with its settings under your own name, such as gold-stars. It then shows in each moment’s list where it fits. Rename or remove it there; the moments that use it follow. In the theme JSON: "recipes": { "gold-stars": { "effect": "confetti", "count": 120, "colors": ["warning"] } }, and a moment uses it with "drop": { "effect": "gold-stars" }.

The wallpaper behind pages

Hubs, dashboards, views, the calendar, chats and the feed wear the theme’s wallpaper. A collection page and an entry page (a note, a task) are plain: the theme’s background colour, so tables and text are easy to read. Sidebars, menus and panels stay solid; only the page shows the picture.

  • Which picture. Your pick in Settings → Appearance → Background, else the theme’s own wallpaper, else the Sakura picture. A soft wash of the page colour lies over it, so text stays easy to read.
  • One setting for every page. In Settings → Appearance → Background, the checkbox Wallpaper behind pages turns it off and on for the whole app. Off, every page is plain; a chat still shows its own picture if it has one.
  • A page can change its own. A collection, a global collection or a dashboard: open its banner menu, then Background. A hub: its ••• menu, then Page background…. Pick a picture to wear that one instead. Pick a colour to make the page plain. Pick Theme to go back to the default (with Undo). A collection is plain until you pick a picture for it.

Example: you open your Home hub. The Sakura picture sits behind its tabs and dashboard cards. You open your Push-ups collection, then a task: both pages are plain.

Three layers

A theme has three layers. Each layer points to the layer above it. So one change flows into everything that uses it.

The three layers of a theme. Ingredients feed meanings, and meanings feed the look of each part.1. Ingredientsyour palette, fonts, size steps, spacing steps, shadow steps, speedspalette.sunset2. Meaningswhat each value is forcolor.accent3. Partsthe default look of each name tagcheckbox: circle
Change the sunset orange once, and the accent, and every part that uses the accent, follow.
Layer Holds Example Who changes it
Ingredients the raw values palette.sunset is an orange you picked rarely
Meanings what each value is for color.accent uses palette.sunset; text.body is 15 px sometimes; most themes change only these
Parts the default look of each name tag checkbox.shape is circle; toast.position is bottom when you want one part to differ

Three quick knobs

Most people only touch these, plus the accent colour, the font and the background:

Knob What it does Values
scale.text makes all text bigger or smaller 80–140%
scale.space makes everything tighter or looser compact, comfortable, spacious
scale.round makes corners sharper or rounder from sharp to very round

How a theme behaves

  • Light and dark. Every colour has a light value and a dark value. The app picks the right one.
  • Your theme stores only your changes. The built-in theme has every value filled in. Your theme lists what you changed on top of it. When we improve the built-in theme, you get the improvement for everything you did not change.
  • A copied theme keeps its base. Copy a theme from the Library, and your changes sit on top of it. When its author improves it, you get an offer with a before and after view. Your changes stay.
  • Effects are part of the theme. The delete dust, the tick confetti and the other moments come with every built-in theme.
  • So are the other modular parts: the icon set, phone vibration, transitions, empty states and the emoji style. Sounds come later and are off by default.
  • Import and export. A theme can move in and out as a design-token file (the shared DTCG 2025.10 format). So a theme made in Figma with Tokens Studio can come in.

Example

A theme with a warm accent, a slightly larger text size, round checkboxes and toasts at the top:

{
"version": 1,
"contract": 1,
"base": "kaizendex.light",
"scale": { "text": 105, "space": "comfortable", "round": "round" },
"color": { "accent": "var(--palette-sunset)" },
"text": { "body": { "size": 15, "lineHeight": 1.5 } },
"parts": {
"checkbox": { "shape": "circle" },
"toast": { "position": "top" },
"toast.error": { "background": "var(--color-danger)" }
},
"moments": { "entry.delete": { "effect": "dust" } }
}