Skip to content

Theme settings

Every key a theme can hold, grouped by layer. Each key will also be a CSS variable: color.accent as --color-accent, radius.card as --radius-card. Today the colour variables keep the old app’s names (see The file today).

The theme document

Key Holds
version the file version
contract the name-tag contract version the theme was written for
base the theme it builds on, for example kaizendex.light or a Library theme (optional)
palette ingredients: your colours
fonts ingredients: your fonts
scale the three quick knobs
color, text, space, radius, shadow, motion, width meanings
background the main background
parts the default look of each name tag
moments, recipes effects and your saved effect recipes
icons, haptics, sounds, transitions, emptyStates, emoji the modular parts
when screen-size and other condition rules

A theme stores only what you changed. A key you leave out uses the base. A key set to null goes back to the base value.

The file today

Settings/theme.json is { "version": 2, "themes": [...], "preferences": {...} }. Each theme has id, name, type (light or dark) and the layers. The old app’s names map like this:

Old app In theme.json CSS variable today
colour background, foreground, surface, surface-foreground color.background, color.text, color.surface, color.surfaceText --color-background, --color-foreground, …
colour muted, muted-foreground color.muted, color.textMuted --color-muted, --color-muted-foreground
colour primary, primary-foreground color.accent, color.accentText --color-primary, --color-primary-foreground
colour accent, accent-foreground (the hover fill) color.hover, color.hoverText --color-accent, --color-accent-foreground
colour ring, link, border, border-strong color.focus, color.link, color.border, color.borderStrong --color-ring, --color-link, …
colour success, warning, destructive, info color.success, color.warning, color.danger, color.info --color-destructive for danger
fonts sans, mono, display, heading, numeral fonts.body, fonts.code, fonts.display, fonts.heading, fonts.number --font-sans, …
type scale caption, meta, body, title, heading, h2, h1, display text.caption, text.bodySmall, text.body, text.title, text.heading3, text.heading2, text.heading1, text.display, each { "size", "lineHeight" } --text-<old name>
density scale.space (compact, comfortable)
control groups (checkbox, table, navigation, page, panel, scrollbar, …) parts.<group>; the checkbox uses borderWidth, borderColor, background
region colours "sidebar.primary" parts.sidebar.accent (other keys such as chart-1 keep their names)
wallpaper, chat background, celebration, base theme background: { "fill": "image", "image": … }, parts.chats.wallpaper, moments["checkbox.tick"], base
icons, glass, deck icons, glass, deck
scale (text size, corners) scale.text (80–140), scale.round (sharp, soft, round, veryRound) every --text-* size; --radius-* and the control, button and panel corners
motion motion.level (off, calm, normal, extra) html[data-motion-level]
moments (all but a plain tick) moments.<name>.effect
otherSide the other side of each { "light", "dark" } colour the theme in the other mode
recipes recipes.<name> (effect, count, colors); a moment names one as its effect

A colour can be one value or { "light": …, "dark": … }. A theme shows its own side (type) and, when it has pairs, the other side in the other mode. Keys the old app has no place for (a one-sided pair, a text style’s weight) stay in the file when you edit the theme.

Layer 1: ingredients

The raw values. Meanings point to them.

Ingredient What it is Example
palette named colours, each with a light and a dark value palette.sunset, used as var(--palette-sunset)
fonts built-in fonts, or font files you upload (asset:…) "body": "Inter", "heading": "asset:fraunces"
size steps the text size steps not decided yet
spacing steps 2, 4, 6, 8, 12, 16, 24, 32, 48, 64 space.cardPadding uses step 4
roundness steps corner radius steps not decided yet
shadow steps shadow strengths not decided yet
animation speeds how fast motion runs not decided yet

The key names for the size, roundness, shadow and speed steps are not decided yet.

Layer 2: meanings

What each value is for. Most themes change only these.

Group Keys
Colours (color.*) background, surface, surfaceText, surfaceRaised, overlay, muted, hover, hoverText, text, textMuted, textFaint, border, borderStrong, accent, accentText, success, warning, danger, info, focus, selection, highlight, searchHighlight, link, chart1 to chart12
Text (text.*) body, bodySmall, label, caption, title, heading1, heading2, heading3, display, number, code
Fonts font.body, font.heading, font.display, font.number, font.code
Spacing (space.*) page, section, gap, cardPadding, controlPadding, rowHeight, controlHeight
Shapes (radius.*) control, card, panel, dialog, chip
Depth shadow.card, shadow.menu, shadow.dialog, shadow.toast, blur.glass
Motion (motion.*) fast, normal, slow, ease, bounce, celebrate, and level
Widths (width.*) form, reading, page, board, content

Every colour has a light and a dark value. The app picks the right one.

Each text style has a size, line height, weight, letter spacing and font. Sizes are plain numbers in pixels. Grouped values are objects, never shorthand strings:

{ "text": { "body": { "size": 15, "lineHeight": 1.5 } } }

motion.level is one knob for all effects: off, calm, normal or extra.

The quick knobs

Key Values
scale.text 80 to 140 (percent)
scale.space compact, comfortable, spacious
scale.round from sharp to very round (for example round); the full list of steps is not decided yet

The background

The same shape works on app.background, the sidebar, pages, views, dashboards, blocks and cards.

Key Values
fill theme, color, gradient, image, clear (nothing, so what is behind shows), and glass (frosted) on the sidebar, pages and cards
color a colour, for fill: color
from, to the two colours, for fill: gradient
image an uploaded file (asset:…), never a web link
fit cover, contain or tile
position where the image sits
dim how much to darken the image
blur how much to blur the image

The sidebar, pages and cards can each be solid, glass (frosted) or clear. Text on a background always gets the theme’s contrast check.

Layer 3: parts

parts sets the default look of any name tag. The most used:

Tag Settings
checkbox shape (square, rounded, circle, or an uploaded SVG), size, border, fill when ticked (checkedFill), mark (check, dot, cross, heart, star, or an uploaded SVG)
button and its kinds background, text, border, radius, padding, height, font weight, icon size, hover, pressed, disabled
input and its kinds height, background, border, radius, padding, focus ring, placeholder colour, the picker’s look, the rating’s symbol
select, menu trigger look, list background, item height, item radius, icon size, check mark, separator, shadow, search box, how it opens
dialog and its kinds width, radius, padding, background, overlay colour and blur, how it opens and closes, header and footer look
toast and its kinds position, width, background per kind, icon, radius, shadow, how it enters and leaves, how long it stays, how many stack
sidebar width, background, font, row height, spacing, icon size, the current page’s look, section titles, how it collapses
tag shape, padding, font, colours per tag colour
tabs, tooltip, infoHint, scrollbar, dragHandle, focusRing sizes, colours and motion
tabs.bar (the one tab bar of collection, global collection and hub pages) the tab look, the link mark (↗), the More ▾ menu, the + button, truncate and overflow
label (the icon and the name) what shows (show), icon size, truncate
every label tag truncate: how long text is cut (see below)
card, row, and each view’s (feed.card, board.card, list.row, …) padding, radius, background, border, shadow, hover, the default layout
page, entryPage, collectionPage, hubPage background, width, padding, header look
grid the gap between tiles, the look of each tile, and the smallest tile that may show another entry’s Dashboard property (see below)
block and its kinds the block’s frame; a chart’s colours come from color.chart1 to chart12 unless set

The exact key name of each setting is not decided yet, except where the plan’s examples show one (shape, size, mark, checkedFill, position, radius, background, width) and the settings below (truncate, overflow, show, and the scroll bar’s keys).

Scroll bars: scrollbar

Every theme starts with Notion’s scroll bar, the simple style: one thin bar, the same on every surface (pages, the feed, chats, Settings, dialogs, menus, text boxes and a table’s sideways bar). It has no arrow buttons. It shows while you point at that area or scroll it, in two theme colours, and grows a little under the pointer. Each page has one bar, along its right edge, under the page’s header row. Tab rows have none.

Key What it sets Default
parts.scrollbar.thumb the part you drag (--color-scrollbar-thumb) the theme’s quiet text colour (color.textMuted) at 50%
parts.scrollbar.track the groove behind it (--color-scrollbar-track) clear
parts.scrollbar.style the bar’s look simple; or one of the older looks: dots, pill, groove, capsule, hatch, thin, native

The two colours are hex values, such as "thumb": "#a8a29e". The older looks keep their own colours and sizes. You can also pick the look in Settings → Appearance → Scrollbars → Style.

Long text: truncate and overflow

Every label tag has a truncate setting. A label tag is a tag that shows a name or a short text: a tab, a sidebar row, a chip, a button, a table cell, a menu item, a breadcrumb item, a card title, and the label tag itself. The rules behind it are on When text is too long.

Key What it does Values Built-in theme
truncate.lines how many lines the text may take before it is cut 1 to 6 1 for labels; card titles use the card’s own setting
truncate.cut where the text is cut end · middle · start · none (never cut) end; middle for file names and ids
truncate.minWidth the narrowest the label may get before it is cut pixels (80) or characters ("6ch", six characters wide) not decided yet
truncate.marker the sign that shows the cut any short text "…"
overflow (on tabs.bar only) what happens when the tabs do not fit menu (the More ▾ menu) · scroll · wrap (two rows) menu
{
"parts": {
"tabs.bar": {
"truncate": { "lines": 1, "cut": "end", "minWidth": "6ch" },
"overflow": "menu"
}
}
}

Names and icons: the label tag

The label tag is the one icon-and-name control. It sits inside every tab, every sidebar row, every title, and the small header of an Entry block that shows one property. Its pieces are icon and name.

Key What it does Values
show what the label shows both (icon and name) · icon · name

The theme sets what shows by default. You can still choose for one tab, row, hub or collection in its own icon-and-name control. An entry page title always shows its name.

This theme shows only icons in tabs and sidebar rows. Entry page titles still show their names.

{ "parts": { "label": { "show": "icon" } } }

Embeds in a Dashboard

An Entry block can show one property of an entry. When that property is a Dashboard, such as a dashboard’s Dashboard property, it needs room for its own tiles. So grid has a setting for the smallest tile that may show it. A Block page shown this way has no smallest tile.

Setting Built-in theme In a smaller tile
the smallest tile for a Dashboard shown as one property 6 columns wide and 4 rows high the entry shows as its card

The key name is not decided yet. On a phone, tiles are full width, so this setting does not apply there. The depth limit (3 levels) and the loop rule apply to a Dashboard and a Block page. They are not theme settings. See Blocks and charts.

Moments and modular parts

moments holds one effect per moment. See Moments for every moment, effect and recipe.

Key What it decides Default
icons the icon set, stroke width and size the house set
haptics the phone vibration per moment: none, light, medium, success, warning light on tick, success on all done, warning on error
sounds (later) a sound per moment, from a built-in pack or an uploaded short sound off
transitions how pages, peeks, sheets and dialogs open and close a quick fade and slide
emptyStates what an empty view shows: nothing, a short line, or a picture a short line
emoji the system’s emoji, or one built-in emoji style the system’s

A full example

{
"version": 1,
"contract": 1,
"base": "kaizendex.light",
"fonts": { "body": "Inter", "heading": "asset:fraunces" },
"scale": { "text": 105, "space": "comfortable", "round": "round" },
"color": { "accent": "var(--palette-sunset)" },
"text": { "body": { "size": 15, "lineHeight": 1.5 } },
"background": { "fill": "image", "image": "asset:mountains", "fit": "cover", "dim": 20 },
"parts": {
"checkbox": { "shape": "circle" },
"toast": { "position": "top", "radius": "var(--radius-panel)" },
"toast.error": { "background": "var(--color-danger)" },
"sidebar": { "background": { "fill": "glass" }, "width": 260 },
"tabs.bar": { "truncate": { "minWidth": "6ch" }, "overflow": "scroll" },
"dialog.newEntry": { "width": 560 }
},
"moments": {
"entry.delete": { "effect": "dust" },
"checkbox.tick": { "effect": "pop" }
},
"motion": { "level": "normal" }
}